feat(title): add recipe and tokens by thetaPC · Pull Request #31539 · ionic-team/ionic-framework

thetaPC · 2026-10-06T22:14:41Z

Issue number: resolves internal

What is the current behavior?

ion-title does not fragment styles based on themes.

What is the new behavior?

Migrates ion-title to Modular Ionic: one token-driven stylesheet, IonTitleRecipe and IonTitleConfig, and per-theme token defaults for ios, md and ionic.
Adds a hue prop (bold by default, or subtle). The ionic theme now applies color, matching ios and md. The hue test covers every color in ios, md and ionic, so the separate color test is removed.
The ionic title's padding moves from the toolbar into the title's tokens, so an ionic title outside a toolbar now gets the same inline padding as ios and md.
size accepts medium, which is the default from the new IonTitle.size config. The header's condense effect also reads that config, so a title made large through it condenses. Size classes are now title-size-small, title-size-medium and title-size-large, and toolbar's matching classes are toolbar-title-size-*.
Replaces --color with --ion-title-color, which also reaches the copy of a large title shown during the iOS page transition.
Removes runtime theme branching (getIonTheme and the theme virtual prop) and the title-rtl class.
box-sizing: border-box and pointer-events: none are set in the stylesheet for every theme instead of through tokens. In md, a tap on the title's padding now reaches the toolbar, as it already did in ios and ionic.
The iOS large title's min-width: 100% moves to toolbar.ios.scss, next to the flex-wrap rule it works with.
iOS small title inset: the small title's side padding is now --ion-spacing-lg (16px) instead of 9px, matching the navigation bar prompt in Apple's iOS 17 and 18 design kits. Long small titles wrap a little sooner.
md title letter spacing: now 0.0075em (0.15px at 20px) instead of 0.0125em, matching Headline 6 in Google's Material 2 design kit. The old value came from a 2019 toolbar update (fix(toolbar): update md toolbar button spacing and segment padding #17537).
Removes the iOS toolbar's large title rule and its title-large order value. The rule's selector can't reach the slotted title, so it never applied, and the title already computes order: 0. Rendering doesn't change.
Adds a dynamicFontMax token helper, and rounds scaled sizes in dynamicFontMin and dynamicFontMax.
Snapshot changes: every md screenshot that shows a title changes on the title row only, because the tighter letter spacing shifts the text slightly. That includes other components' pages, such as the popover header and the page header behind an action sheet. The iOS title-basic screenshots change where the long small title wraps. The hue screenshots now include ios. In header's "root iOS header in an MD app" screenshot, the title follows the page's theme: an ancestor mode attribute now only affects behavior, as it already does for every migrated component.

Does this introduce a breaking change?

Yes
No

ion-title CSS variables and classes are replaced by token-driven custom properties and prop-named classes. Use the global token for theme-wide styling, or the CSS variable for component-specific overrides.

Color

Old	Token (global)	CSS variable (component-specific)
`--color`	`IonTitle.color`	`--ion-title-color`

Size classes

Old	New
`title-default`	`title-size-medium`
`title-small`	`title-size-small`
`title-large`	`title-size-large`
`toolbar-title-default`	`toolbar-title-size-medium`
`toolbar-title-small`	`toolbar-title-size-small`
`toolbar-title-large`	`toolbar-title-size-large`

RTL class: title-rtl is removed. Use ion-title:dir(rtl) instead.
Theme classes: remove any instances that target ion-title.md or ion-title.ios.
Taps on the title's padding: in md, a tap on the padding at the start or end of ion-title now reaches the element behind it, usually ion-toolbar. Listen on ion-toolbar if those taps need to count.

Other information

Left for the parents

Some ion-title styles still live in, or depend on, its parents. They move with that parent's work, so they aren't part of this PR.

Toolbar (FW-6864): the text-align rules in toolbar.ionic.scss, the iOS title's own centering and its 90px side padding in title.scss (marked TODO(FW-6864)), and the iOS large title's full-width row in toolbar.ios.scss. Once the toolbar places the title in every theme, the title's centering and side padding can go.
Header scroll effects: the rules in header.common.scss that hide and fade the title as the large title collapses. They depend on the header's scroll state and include its condense motion, so they move in the header migration (FW-6843).

How to test

Open each before and after link side by side.

Check	Before	After	What to look for
Color, ionic theme	none, the color page is replaced by the hue page	after	Each titled color is drawn in that color. Before this PR, the ionic theme drew every title dark gray
Hue, every theme	none, new page	ios, md and ionic	The bold titles use the full color, and the subtle titles a muted one
No theme	before	after	Before, titles use the md styles. After, they render as plain text with no padding, which is how a migrated component looks without a theme
Basic, ios theme	before	after	Looks the same, except the long small title in the blue toolbar, which has more room at its sides and can wrap a word sooner
Basic, md theme	before	after	Looks the same, with titles very slightly tighter from the letter spacing
Basic, ionic theme	before	after	Looks the same on both, including the titles' padding, which now comes from the title instead of the toolbar

vercel · 2026-10-06T22:14:50Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
ionic-framework	Ready	Preview	Oct 22, 2026 5:52pm UTC

thetaPC · 2026-10-06T22:16:15Z

The title in this snapshot now follows the page's md theme instead of the header's mode="ios", since migrated components take their look from the theme and mode only affects behavior; the header itself is still visible, which is what the test checks.

brandyscarney

Looks good! I requested some changes. 🙂

Co-authored-by: Brandy Smith <brandyscarney@users.noreply.github.com>

…kens

brandyscarney

Looks good just one optional change in the interface!

# Conflicts: # core/src/components/title/test/color/title.e2e.ts

Co-authored-by: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>

# Conflicts: # core/src/components/title/test/color/title.e2e.ts-snapshots/title-color-ionic-md-ltr-light-Mobile-Chrome-linux.png # core/src/components/title/test/color/title.e2e.ts-snapshots/title-color-ionic-md-ltr-light-Mobile-Firefox-linux.png # core/src/components/title/test/color/title.e2e.ts-snapshots/title-color-ionic-md-ltr-light-Mobile-Safari-linux.png # core/src/components/title/test/color/title.e2e.ts-snapshots/title-color-ios-ltr-Mobile-Chrome-linux.png # core/src/components/title/test/color/title.e2e.ts-snapshots/title-color-ios-ltr-Mobile-Firefox-linux.png # core/src/components/title/test/color/title.e2e.ts-snapshots/title-color-ios-ltr-Mobile-Safari-linux.png # core/src/components/title/test/color/title.e2e.ts-snapshots/title-color-md-ltr-Mobile-Chrome-linux.png # core/src/components/title/test/color/title.e2e.ts-snapshots/title-color-md-ltr-Mobile-Firefox-linux.png # core/src/components/title/test/color/title.e2e.ts-snapshots/title-color-md-ltr-Mobile-Safari-linux.png

ShaneK

Looks really good overall! Just a few things, mainly the transition copy losing hue and the two visual changes missing from the breaking changes doc. The rest are smaller.

ShaneK · 2026-10-22T19:38:35Z

@@ -17,7 +17,7 @@ export const shadow = <T extends Element>(el: T): ShadowRoot | T => {

 const getLargeTitle = (refEl: any) => {
  const tabs = refEl.tagName === 'ION-TABS' ? refEl : refEl.querySelector('ion-tabs');
-  const query = 'ion-content ion-header:not(.header-collapse-condense-inactive) ion-title.title-large';
+  const query = 'ion-content ion-header:not(.header-collapse-condense-inactive) ion-title.title-size-large';


The copy of the large title used in this transition gets size and color from the real title in animateLargeTitle, but not the new hue. So a large title with color="primary" hue="subtle" renders at rgb(0, 74, 205), but its copy animates in the bold color, rgb(0, 84, 233), on both push and pop and then switches back when the real title shows again. Copying hue across keeps it subtle the whole way through:

clonedTitleEl.color = largeTitleEl.color; clonedTitleEl.hue = largeTitleEl.hue;

ShaneK · 2026-10-22T19:41:27Z

+        bold: {
+          semantic: {
+            default: {
+              color: currentColor('base'),


Is base intentional here? The subtle hue reads foreground, and ion-text uses foreground for both hues since it moved off base in #31170. With primary on ios, a bold title comes out rgb(0, 84, 233) and a subtle one rgb(0, 74, 205), so subtle is actually darker than bold, and a primary title doesn't match a primary ion-text either. If it's meant to keep the current look that's fine, otherwise md and ionic have the same line.

ShaneK · 2026-10-22T19:45:15Z

+3. The size classes now include the property name, and a title without `size` is now `medium`. <sup>[3](#version-10x-title-size-classes)</sup>
+4. The `title-rtl` class has been removed. <sup>[4](#version-10x-title-rtl-class)</sup>
+5. Theme classes (`ion-title.md`, `ion-title.ios`) are no longer supported. <sup>[5](#version-10x-title-theme-classes)</sup>
+6. In the `md` theme, a tap on the title's padding no longer counts as a tap on the title. <sup>[6](#version-10x-title-padding-taps)</sup>


I think the iOS small title padding (9px to 16px) and the md letter spacing (0.0125em to 0.0075em) should go in here too, since Button, Card and Chip all list their default visual changes. Setting --ion-title-size-small-padding-start and --ion-title-size-small-padding-end to 9px, or --ion-title-letter-spacing to 0.0125em, brings the old look back, so those could be the revert path.

ShaneK · 2026-10-22T19:47:42Z

+  // TODO(FW-6864): remove for small and medium when ion-toolbar titlePlacement works in every theme (ios center, md start)
+  position?: string;


Could we drop position for large too? Only the medium title is absolutely positioned now, so the static iOS sets for large is just the default, and unsetting it doesn't move the title at all. The TODO only removes it for small and medium, so large would keep position as a public token after FW-6864, which I think is what Brandy wanted to avoid.

ShaneK · 2026-10-22T19:49:26Z

+:host(.toolbar-title-size-large) .toolbar-container {
  flex-wrap: wrap;
  align-items: flex-start;
 }

-:host(.toolbar-title-large) .toolbar-content ion-title {
-  flex: 1;
-  order: map-get($toolbar-order-ios, title-large);
-
+// The large title fills a row of its own, so the wrap moves it below the buttons
+:host(.toolbar-title-size-large) ::slotted(ion-title) {
  min-width: 100%;
 }


Suggested change

:host(.toolbar-title-size-large) .toolbar-container {

flex-wrap: wrap;

align-items: flex-start;

}

:host(.toolbar-title-large) .toolbar-content ion-title {

flex: 1;

order: map-get($toolbar-order-ios, title-large);

// The large title fills a row of its own, so the wrap moves it below the buttons

:host(.toolbar-title-size-large) ::slotted(ion-title) {

min-width: 100%;

}

:host(.toolbar-title-size-large) .toolbar-container {

flex-wrap: wrap;

align-items: flex-start;

}

I know this came out of an earlier suggestion, but I don't think it does anything. The title is slotted into .toolbar-content, so it isn't a flex item of the wrapping .toolbar-container and can't be pushed onto its own row. With start and end buttons, a long title or the condense header, the large title stays on the same row either way, and removing the rule doesn't change any title, header or toolbar screenshot. The old rule in title.ios.scss didn't do anything either, so this isn't a regression.

ShaneK · 2026-10-22T19:52:28Z

@@ -33,7 +33,7 @@
        </ion-header>

        <ion-header>
-          <ion-toolbar class="toolbar-title-default">
+          <ion-toolbar class="toolbar-title-size-medium">


The setContent copy of this markup in title.e2e.ts still has the old toolbar-title-default class:

<ion-toolbar class="toolbar-title-size-medium">

Renaming it there doesn't change any of the basic screenshots. This is just a nit though, up to you!

thetaPC added this pull request to stack #31538 October 6, 2026 22:14

github-actions Bot added package: core @ionic/core package package: angular @ionic/angular package package: vue @ionic/vue package package: react @ionic/react package labels Oct 6, 2026

thetaPC commented Oct 6, 2026

View reviewed changes

vercel Bot deployed to Preview October 6, 2026 22:32

View deployment

vercel Bot deployed to Preview October 10, 2026 02:34

View deployment

vercel Bot deployed to Preview October 12, 2026 15:38

View deployment

thetaPC mentioned this pull request Oct 12, 2026

test(title): add color and rtl coverage #31537

Open

1 of 2 tasks

thetaPC marked this pull request as ready for review October 12, 2026 18:13

thetaPC requested a review from a team as a code owner October 12, 2026 18:13

thetaPC requested a review from ShaneK October 12, 2026 18:13

brandyscarney requested changes Oct 16, 2026

View reviewed changes

thetaPC and others added 15 commits October 19, 2026 19:45

feat(title): add recipe and tokens

dcc2b55

chore(): run lint

0163d99

fix(header): detect a large title set through config

86fca06

refactor(title): remove unused element and destructure color

8c8937d

docs(title): explain the translateZ transform

82ce8b2

test(title): cover hue classes and config defaults

03d09ce

refactor(title): move the ionic title padding out of the toolbar

a74205a

refactor(toolbar): remove the unused ios large title rule

3b8c53e

docs(toolbar): fix a typo in the slot placement comment

f6d82ac

Co-authored-by: Brandy Smith <brandyscarney@users.noreply.github.com>

docs(breaking): render code in the title headings

7a1ecb5

Co-authored-by: Brandy Smith <brandyscarney@users.noreply.github.com>

docs(breaking): move the toolbar title classes to the toolbar section

9c693d7

test(title): remove the color test now that hue covers it

c986975

test(title): render the hue test with setContent and include ios

c8977ef

refactor(toolbar): give the ios large title its own row from the toolbar

3fbbd93

refactor(title): set box-sizing in the stylesheet instead of a token

4b265bb

thetaPC added 5 commits October 19, 2026 19:45

refactor(title): set pointer-events in the stylesheet instead of a token

05d1349

docs(title): mark the temporary position tokens for FW-6864

a111599

docs(title): mark the ios medium side padding for FW-6864

819c21c

fix(title): match the ios small title inset to the iOS design kits

f492478

fix(title): match the md title letter spacing to Material Design 2

e376b50

thetaPC force-pushed the FW-6863 branch from 035a4ee to e376b50 Compare October 20, 2026 02:47

vercel Bot deployed to Preview October 20, 2026 02:52

View deployment

chore(): add updated snapshots

941687c

vercel Bot deployed to Preview October 20, 2026 15:48

View deployment

test(title): move the snapshot updates to their own PR

0d9570b

vercel Bot deployed to Preview October 20, 2026 21:34

View deployment

chore(): add updated snapshots

2e2df52

This was referenced Oct 20, 2026

test(title): update snapshots for the title migration #31614

Closed

test(title): update snapshots for the title migration #31615

Merged

refactor(title): set width and height in the stylesheet instead of to…

42ff788

…kens

vercel Bot deployed to Preview October 20, 2026 22:41

View deployment

thetaPC requested a review from brandyscarney October 20, 2026 23:13

brandyscarney approved these changes Oct 21, 2026

View reviewed changes

Comment thread core/src/components/title/title.interface.ts Outdated

Merge remote-tracking branch 'origin/FW-6863-tests' into FW-6863

8409472

# Conflicts: # core/src/components/title/test/color/title.e2e.ts

vercel Bot deployed to Preview October 22, 2026 17:41

View deployment

thetaPC and others added 2 commits October 22, 2026 10:47

refactor(title): nest the large title's align-items token

1b903dd

Co-authored-by: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>

vercel Bot deployed to Preview October 22, 2026 17:52

View deployment

ShaneK requested changes Oct 22, 2026

View reviewed changes

		// TODO(FW-6864): remove for small and medium when ion-toolbar titlePlacement works in every theme (ios center, md start)
		position?: string;

Conversation

thetaPC commented Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the current behavior?

What is the new behavior?

Does this introduce a breaking change?

Other information

Left for the parents

How to test

Uh oh!

vercel Bot commented Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thetaPC Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

brandyscarney left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brandyscarney left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ShaneK left a comment

Choose a reason for hiding this comment

Uh oh!

ShaneK Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

ShaneK Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

ShaneK Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

ShaneK Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

ShaneK Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

ShaneK Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

thetaPC commented Oct 6, 2026 •

edited

Loading

vercel Bot commented Oct 6, 2026 •

edited

Loading