feat(item-divider): add recipe and tokens by thetaPC · Pull Request #31009 · ionic-team/ionic-framework

thetaPC · 2026-03-11T23:16:14Z

Issue number: internal

What is the current behavior?

Component styles for ion-item-divider are fragmented across multiple files (ios, md). The ionic theme uses the md styles. Developers were restricted to those themes and how those themes structured the logic and styles.

What is the new behavior?

Unified Style Architecture: Combined theme-specific styling into a single item-divider.scss file that consumes CSS variables, ensuring a single source of truth for component logic.
Anchor-Edge model: expanded the property-first approach into an anchor-edge model to account for the amount of slot usage
Defined TypeScript Interface: Added item-divider.interfaces.ts
Defined Shared Base Defaults: Added defaults that are being used regardless of theme
Defined Shared Theme Defaults: Added defaults that are being used per theme
Updated Test Page: Updated the dividers test page to include more cases

Does this introduce a breaking change?

Yes
No

This PR introduces a breaking change to how IonItemDivider is styled. Existing manual CSS overrides targeting internal item divider structures or old token names will no longer work due to the shift to thew new token hierarchy and a unified base SCSS file.

Migration Path:

Token Updates: Update any custom theme configurations to match the new nested structure.
CSS Overrides: Ensure selectors align with the new slotted element logic and variable names (e.g., --ion-item-divider-background).

--background should no longer be used. Setting the value, IonDivider.background, within the tokens file should be used to change the background.

Theme classes: Remove any instances that target the theme classes: ion-divider.md

Other information

This PR significantly improves the developer experience for theming. By moving logic into default.tokens.ts and away from hardcoded SCSS functions, designers and developers can now override styles (like the size on a slotted avatar) purely through token configuration.

Preview

vercel · 2026-03-11T23:16:19Z

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

Project	Deployment	Actions	Updated (UTC)
ionic-framework	Ready	Preview, Comment	Mar 20, 2026 10:06pm

thetaPC · 2026-03-12T18:34:18Z

core/src/components/item-divider/item-divider.scss

+// Slotted Content
+// --------------------------------------------------
+
+::slotted(h1) {


My following comment applies to all the slotted headers:

I noticed that the margins are being overridden by a high level style for headers. I'm not sure when the margins declared in the item divider ever get applied. This is also being overridden in main. Can we just get rid of the slotted header styles?

thetaPC · 2026-03-12T18:38:36Z

core/src/components/chip/chip.scss

Noticed that color functions were never used.

thetaPC · 2026-03-12T18:42:03Z

core/src/components/item-divider/item-divider.scss

+  // TODO(FW-6862): separate width and height tokens for thumbnails
+  --size: var(--ion-item-divider-thumbnail-width);


To maximize customization, we should split the size into height and width.

thetaPC · 2026-03-12T18:42:07Z

core/src/components/thumbnail/thumbnail.scss

   * @prop --size: Size of the thumbnail
   */
-  --size: 48px;
+  --size: 48px; // TODO(FW-6862): separate width and height tokens for thumbnails


To maximize customization, we should split the size into height and width.

thetaPC · 2026-03-12T18:47:42Z

core/src/components/thumbnail/thumbnail.scss

+  width: var(--size, 48px);
+  height: var(--size, 48px);


We're using --ion-item-divider-thumbnail-width to let dividers control thumbnail sizes. The problem is that if a theme doesn't provide this token, the CSS breaks instead of falling back. We can't use revert-layer because the 'original' size we want to return to is actually another variable, not a fixed value. The cleanest fix is to just bake the default 48px right into the variable's fallback.

thetaPC · 2026-03-12T18:50:39Z

core/src/components/item-divider/item-divider.scss

+
+:host([slot="start"]) {
+  @include mixins.margin(
+    var(--ion-item-divider-leading-anchor-margin-top, revert-layer),


revert-layer is being used so that if we don't provide a modular CSS variable, we give the component permission to just keep doing whatever it was doing originally.

thetaPC · 2026-03-13T14:04:06Z

core/src/components/item-divider/item-divider.interfaces.ts

+  leading?: {
+    // Targets `:host([slot="start"])`
+    anchor?: {
+      margin?: IonMargin;
+    };
+
+    // Targets `::slotted([slot="start"])`
+    edge?: {
+      margin?: IonMargin;
+    };
+  };
+
+  trailing?: {
+    // Targets `::slotted([slot="end"])`
+    edge?: {
+      margin?: IonMargin;
+    };
+  };


💡 Naming Convention: Anchors & Edges

To maintain consistency with the Ionic Modular architecture established in ion-chip, this component adopts a shared spatial vocabulary. While chips use DOM order (:first-child), dividers use named slots (slot="start/end"). The following naming convention bridges that gap:

Anchors (:host): Refers to the component's own placement within a parent container.

leading-anchor: Targets :host([slot="start"]).

trailing-anchor: Targets :host([slot="end"]).

Edges (::slotted): Refers to content placed at the boundaries of the component itself.

leading-edge: Targets ::slotted([slot="start"]).

trailing-edge: Targets ::slotted([slot="end"]).

Why this matters:
This mirrors the leading (:first-child) and trailing (:last-child) pattern used in chips. By using leading/trailing instead of left/right or start/end, we create a less confusing structure that developers can use with ease.

thetaPC · 2026-03-13T14:04:43Z

core/src/components/item-divider/item-divider.interfaces.ts

+    default?: {
+      color?: string;
+    };
+
+    semantic?: {
+      default?: {
+        color?: string;
+      };
+    };


This follows the same structure established in chip when it came to default vs semantic colors.

thetaPC · 2026-03-13T14:06:07Z

.../item/test/dividers/item.e2e.ts-snapshots/item-dividers-diff-ios-ltr-Mobile-Chrome-linux.png

Added:

Item divider with icons at the start and end slot

Item divider with a thumbnail at the start

Item divider with paragrahs

thetaPC · 2026-03-13T17:50:10Z

core/src/themes/ionic/shared.tokens.ts

+import { colors as baseColors } from '../base/shared.tokens';
+
+export const components = {
+  item: {


Item divider depends on the values set on item. This file was created to keep track of those values and other components that need to be shared with each other.

ShaneK

This is looking really good so far! I just noticed a few inconsistencies and had question. I may be way off base on some of what I think I found, but just making sure I understand things right!

ShaneK · 2026-03-20T17:08:38Z

core/src/components/item-divider/item-divider.scss

+    var(--ion-item-divider-note-margin-start)
+  );
+
+  align-self: flex-start;


Shouldn't this use --ion-item-divider-note-align-self? You're hard coding it here, but there's a CSS variable prepared for it that's not being consumed?

Good catch! be24a41

ShaneK · 2026-03-20T17:16:37Z

core/src/themes/ionic/shared.tokens.ts

+
+    border: {
+      color: `var(--ion-item-border-color, var(--ion-border-color, var(--ion-background-color-step-150, ${rgba(
+        '0, 0, 0',


Should this be using baseColors.textColorRgb instead of the hardcoded '0, 0, 0'? The md version uses baseColors.textColorRgb for this same border color which lets it respond to --ion-text-color-rgb customization, but this one won't. You're already using baseColors.textColorRgb correctly for the icon color on line 47 so I'm guessing this is just a copy-paste miss?

Good catch! 8595353

ShaneK · 2026-03-20T17:16:47Z

core/src/utils/theme.ts

+ */
+export const dynamicFont = (size: number, unit: string | undefined = baselineUnit): string => {
+  let baselinePixelSize = 16;
+


Does this path actually work? config is a plain object without a .get() method, and this runs at import time before Ionic.config is initialized anyway. So configRootFontSize will always be undefined and you'll always fall back to 16. Is this meant to hook into something that doesn't exist yet, or should we just drop the window check and use the constant?

ShaneK · 2026-03-20T17:18:14Z

core/src/components/item-divider/item-divider.scss

+}
+
+// Paragraph
+::slotted(p) {


Was dropping line-height: normal intentional here? Both the old iOS and MD files had it on ::slotted(p). Without it paragraphs will just inherit from the parent, which is probably fine most of the time but it's a behavior change.

ShaneK · 2026-03-20T17:19:24Z

core/src/components/item-divider/item-divider.scss

-  font-family: $font-family-base;
+  font-family: var(--ion-font-family, inherit);
+  font-size: var(--ion-item-divider-font-size);
+  font-weight: var(--ion-item-divider-font-weight);


iOS previously set font-weight: 600 explicitly but the iOS recipe doesn't define a font.weight token. Without a fallback value here this becomes invalid at computed-value time and falls to inherited/initial (probably normal/400). Should iOS define font.weight in its recipe, or should this have a fallback like var(--ion-item-divider-font-weight, normal)?

ShaneK · 2026-03-20T17:22:10Z

core/src/components/item-divider/item-divider.interfaces.ts

+    };
+  };
+
+  trailing?: {


Something I noticed: trailing means slot="end" here (and in icon.trailing, avatar.trailing, etc.), but down on header2.trailing (line 141) it means :last-child which is the same meaning chip uses for trailing. So the same word means two different things within the same recipe. The anchor/edge vocabulary helps but I think this could still trip people up when working across recipes. Worth thinking about whether there's a clearer way to distinguish these?

ShaneK · 2026-03-20T17:22:48Z

core/src/themes/ios/shared.tokens.ts

+    },
+
+    // Targets `:host([slot="start"])`
+    slot: {


The nesting order here is item.slot.start.margin but ionic and md use item.start.slot.margin for the semantically equivalent thing. I know they target different CSS selectors (:host([slot]) vs ::slotted([slot])) so different naming is defensible, but if someone's adding a new theme or reading across implementations this is going to be confusing. Could we normalize the path structure across all three?

feat(item-divider): add recipe and tokens

20a4a33

github-actions bot added the package: core @ionic/core package label Mar 11, 2026

vercel bot deployed to Preview March 11, 2026 23:17 View deployment

chore(): run build

8295819

vercel bot deployed to Preview March 12, 2026 01:22 View deployment

chore(item-divider): remove theme sass files

38145a3

vercel bot deployed to Preview March 12, 2026 16:29 View deployment

feat(item-divider): remove theme usage

e2cf0e4

github-actions bot added the package: angular @ionic/angular package label Mar 12, 2026

vercel bot deployed to Preview March 12, 2026 16:33 View deployment

docs(item-divider): add todo for border

4b170f0

vercel bot deployed to Preview March 12, 2026 16:39 View deployment

refactor(tokens): rearrange shared tokens

c66561e

vercel bot deployed to Preview March 12, 2026 18:04 View deployment

docs(tokens): update shared file comments

fda52f5

vercel bot deployed to Preview March 12, 2026 18:07 View deployment

thetaPC commented Mar 12, 2026

View reviewed changes

test(item): update divider snapshots

eac584c

vercel bot deployed to Preview March 12, 2026 18:38 View deployment

thetaPC commented Mar 12, 2026

View reviewed changes

core/src/components/chip/chip.scss

Copy link

Contributor Author

thetaPC Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Noticed that color functions were never used.

thetaPC added 2 commits March 12, 2026 11:38

test(item): update divider snapshots again

87e6443

docs(item-divider, thumbnail): update todo

d9db79f

vercel bot deployed to Preview March 12, 2026 18:41 View deployment

thetaPC commented Mar 12, 2026

View reviewed changes

vercel bot deployed to Preview March 12, 2026 18:42 View deployment

thetaPC commented Mar 12, 2026

View reviewed changes

docs(item-divider): update comments

6260629

vercel bot deployed to Preview March 12, 2026 18:59 View deployment

feat(item-divider): revert-layer note font size

fd9f0b5

vercel bot deployed to Preview March 12, 2026 19:07 View deployment

feat(item-divider): add interface

77e50df

vercel bot deployed to Preview March 12, 2026 20:49 View deployment

thetaPC added 2 commits March 13, 2026 06:54

feat(item-divider): cleanup

3336859

revert(chip): import usage

89bcfb4

vercel bot deployed to Preview March 13, 2026 13:57 View deployment

thetaPC commented Mar 13, 2026

View reviewed changes

feat(item-divider): more cleanup

fc0b992

vercel bot deployed to Preview March 13, 2026 14:16 View deployment

thetaPC commented Mar 13, 2026

View reviewed changes

refactor(theme): move baseline pixel

226beaa

vercel bot deployed to Preview March 13, 2026 17:55 View deployment

refactor(theme): update dynamicFont to use root

88bfce3

vercel bot deployed to Preview March 13, 2026 18:42 View deployment

fix(theme): check window

a9f991b

vercel bot deployed to Preview March 13, 2026 18:56 View deployment

thetaPC marked this pull request as ready for review March 13, 2026 21:49

thetaPC requested a review from a team as a code owner March 13, 2026 21:49

thetaPC requested review from BenOsodrac and ShaneK and removed request for BenOsodrac March 13, 2026 21:49

ShaneK requested changes Mar 20, 2026

View reviewed changes

feat(item-divider): use note align self token

be24a41

vercel bot deployed to Preview March 20, 2026 21:55 View deployment

feat(theme): use baseColor token

8595353

vercel bot deployed to Preview March 20, 2026 22:06 View deployment

		// TODO(FW-6862): separate width and height tokens for thumbnails
		--size: var(--ion-item-divider-thumbnail-width);

Conversation

thetaPC commented Mar 11, 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

Uh oh!

vercel bot commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

💡 Naming Convention: Anchors & Edges

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaneK left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

thetaPC commented Mar 11, 2026 •

edited

Loading

vercel bot commented Mar 11, 2026 •

edited

Loading