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

thetaPC · 2026-04-24T23:04:37Z

Issue number: resolves internal

What is the current behavior?

ion-content does not fragment styles based on themes. All 3 themes share one style. However, it's not configured to the Modular Ionic.

What is the new behavior?

Defined TypeScript Interface: Renamed content-interface.ts to content.interfaces.ts and added IonContentRecipe type.
Defined Theme Defaults: Added per-theme token defaults in ios, md, and ionic theme files.
Internal Variable Prefix: Renamed --offset-top / --offset-bottom to --internal-offset-top / --internal-offset-bottom to clearly separate them from the public CSS API.
CSS Logical Properties for RTL: Replaced physical-property RTL selectors on .transition-effect and .transition-shadow with the position-horizontal mixin.
Removed dead property: Dropped -webkit-overflow-scrolling: touch from styles as this property has been a no-op since iOS 13.
Updated Tests: Added unit specs for transitionShadow (present in ios mode, absent in md mode) and the getScrollElement() / getBackgroundElement() element ref methods.
New utility: Replaced inline new Promise((resolve) => componentOnReady(...)) patterns with a shared waitForComponent helper, reducing boilerplate and improving type safety.

Does this introduce a breaking change?

Yes
No

This PR introduces breaking changes to how ion-content is styled.

Migration Path:

CSS Variable Replacements: --background, --color, and --padding-* have been removed. Use the new token structure instead:

--background -> IonContent.background
--color -> IonContent.color
--padding-top -> IonContent.padding.top
--padding-end -> IonContent.padding.end
--padding-bottom -> IonContent.padding.bottom
--padding-start -> IonContent.padding.start

If per-component customization is needed, the CSS variables can be used directly.

--background -> --ion-content-background
--color -> --ion-content-color
--padding-top -> --ion-content-padding-top
--padding-end -> --ion-content-padding-end
--padding-bottom -> --ion-content-padding-bottom
--padding-start -> --ion-content-padding-start

Theme classes: Remove any instances that target the theme classes: ion-content.md, ion-content.ios.

Other information

Previews:

The framework (Angular, React, Vue) test apps are not being styled correctly anymore because the new tokens are not being passed to them. This is expected until we can export the tokens as mentioned in the design doc. The functionality in those test apps are still working.

vercel · 2026-04-24T23:04:41Z

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

Project	Deployment	Actions	Updated (UTC)
ionic-framework	Ready	Preview, Comment	May 5, 2026 1:40pm

thetaPC · 2026-04-30T17:50:58Z

  flex-shrink: 2;
  overscroll-behavior-y: contain;
  overflow-y: auto;
-  -webkit-overflow-scrolling: touch;


-webkit-overflow-scrolling has become obsolete since iOS 13.

thetaPC · 2026-04-30T17:52:32Z

  contain: size style;
 }

-:host(.ion-color) .inner-scroll {


There seems to be a lot deleted, but they were just moved around in the file.

thetaPC · 2026-04-30T17:53:08Z

  @Method()
  async getBackgroundElement(): Promise<HTMLElement> {
    if (!this.backgroundContentEl) {
-      await new Promise((resolve) => componentOnReady(this.el, resolve));


Created a util for this since a lot of components are using the same code

thetaPC · 2026-05-04T22:38:24Z

This change was because I synced the padding between themes to be consistent. ionic wasn't using padding-* on ion-content.

thetaPC · 2026-05-04T22:39:44Z

@@ -32,7 +44,7 @@
        </ion-toolbar>
      </ion-header>

-      <ion-content class="ion-padding-space-400" id="content" no-bounce>


Removed the class because it wasn't set anywhere.

github.com:ionic-team/ionic-framework into FW-6896 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit.

thetaPC · 2026-05-05T03:04:43Z

The goal is to delete this file but that won't be until we can consolidate everything into one base. In the mean time, we should make updates so screenshots don't fail.

thetaPC · 2026-05-05T03:05:42Z

      </ion-header>

-      <ion-content class="ion-padding ion-text-center" id="content" no-bounce>
+      <ion-content class="ion-text-center" id="content" no-bounce>


Added the padding through the config since I already had to pass the background value there. Figured that I would keep it all in one place by adding the padding.

thetaPC · 2026-05-05T03:06:30Z

          background: yellow;
        }

+        #content {


The values are being passed for this specific instance only. The other content components are using the values provided by scripts.js.

thetaPC · 2026-05-05T03:07:46Z

-   * @prop --padding-start: Left padding if direction is left-to-right, and right padding if direction is right-to-left of the content
+   * @prop --ion-content-font-family: Font family of the content
   *
-   * @prop --keyboard-offset: Keyboard offset of the content


I removed the comments for the internal variables.

thetaPC · 2026-05-05T03:14:25Z

+  transform: translateZ(0);
+}
+
+// Content: iOS Mode Transition


The design doc did not account for animations based on mode. Should we be aiming to convert them to be based on themes? If so, then we can allow devs to customize the certain parts of the animations. In this instance, they could provide their preferred background color during the transition.
If we do decide to convert, then a ticket should be made and a TODO should be added here.

thetaPC · 2026-05-05T03:16:13Z

+     * The transition shadow effect is only animated by the iOS transition
+     * builder, so these elements are only rendered in iOS mode.
+     */
+    const transitionShadow = mode === 'ios';


As mentioned in the comment, this is only available in the ios mode as shown in the ios.transition.ts file.

thetaPC · 2026-05-05T03:29:55Z

-            ...customTheme.palette,
-          },
-        };
+        theme = deepMerge(theme, customTheme);


This change mimics exactly how we are loading themes in the theme.ts file.

thetaPC · 2026-05-05T13:40:35Z

+  $padding-top: var(--padding-top, var(--ion-content-padding-top, 0px));
+  $padding-end: var(--padding-end, var(--ion-content-padding-end, 0px));
+  $padding-bottom: var(--padding-bottom, var(--ion-content-padding-bottom, 0px));
+  $padding-start: var(--padding-start, var(--ion-content-padding-start, 0px));


In order for the padding classes (.ion-padding) to still be functional, we should be incorporating them as the first check.

thetaPC · 2026-05-05T13:42:01Z

+:host(.ion-color) .inner-scroll {
+  background: color.current-color(base);
+  color: color.current-color(contrast);
+}


I didn't make this customizable because all themes are using the same styles. If the community requests it, then we can update the recipe to include it.

thetaPC · 2026-05-05T13:48:22Z

 }

 .transition-shadow {
+  @include mixins.position-horizontal(null, 0);


We can now use this mixin instead of having to use left/right!

thetaPC · 2026-05-05T18:08:58Z


+:host(.ion-color) .inner-scroll {
+  background: color.current-color(base);
+  color: color.current-color(contrast);


I was going to switch this to use foreground as stated in the ticket but that lead to unwanted changes like:

The text color is not readable in some components. Others, it's too light and I question if it would pass accessibility.

We should look into the foreground values again.

feat(content): add recipe and tokens

7afba1a

github-actions Bot added the package: core @ionic/core package label Apr 24, 2026

vercel Bot had a problem deploying to Preview April 24, 2026 23:05 Failure

thetaPC added 2 commits April 30, 2026 10:00

feat(content): cleanup

32d2fdb

feat(content): more cleanup

57c3140

github-actions Bot added the package: angular @ionic/angular package label Apr 30, 2026

vercel Bot deployed to Preview April 30, 2026 17:03 View deployment

refactor(utils): created waitForComponent

5983c3b

vercel Bot deployed to Preview April 30, 2026 17:37 View deployment

feat(styles): remove webkit-overflow-scrolling

76a32dd

vercel Bot deployed to Preview April 30, 2026 17:50 View deployment

thetaPC commented Apr 30, 2026

View reviewed changes

feat(content): improvements

7646ae6

vercel Bot deployed to Preview April 30, 2026 18:10 View deployment

feat(contenet): remove transition theme

412806f

vercel Bot deployed to Preview April 30, 2026 18:13 View deployment

refactor(contenet): update padding variables

c8f817c

vercel Bot deployed to Preview April 30, 2026 18:36 View deployment

vercel Bot deployed to Preview May 1, 2026 22:36 View deployment

vercel Bot deployed to Preview May 1, 2026 22:51 View deployment

vercel Bot deployed to Preview May 1, 2026 22:57 View deployment

github-actions Bot added the package: vue @ionic/vue package label May 1, 2026

vercel Bot deployed to Preview May 1, 2026 22:59 View deployment

vercel Bot deployed to Preview May 1, 2026 23:08 View deployment

thetaPC force-pushed the FW-6896 branch from 300abbf to c8f817c Compare May 4, 2026 13:22

github-actions Bot removed the package: vue @ionic/vue package label May 4, 2026

feat(content): remove unused config

6a496be

thetaPC commented May 4, 2026

View reviewed changes

vercel Bot deployed to Preview May 4, 2026 22:58 View deployment

feat(content): add css fallbacks

ec39980

vercel Bot deployed to Preview May 5, 2026 03:00 View deployment

feat(content): update core ionic styles

7b8d89c