feat(backdrop): add recipe and tokens

BREAKING.md

@@ -17,6 +17,7 @@ This is a comprehensive list of the breaking changes introduced in the major ver
 
 - [Global Styles](#version-10x-global-styles)
 - [Components](#version-10x-components)
+  - [Backdrop](#version-10x-backdrop)
   - [Button](#version-10x-button)
   - [Card](#version-10x-card)
   - [Checkbox](#version-10x-checkbox)
@@ -51,6 +52,28 @@ This is a comprehensive list of the breaking changes introduced in the major ver
 
 <h2 id="version-10x-components">Components</h2>
 
+<h4 id="version-10x-backdrop">Backdrop</h4>
+
+The following breaking changes apply to `ion-backdrop`:
+
+1. The `--ion-backdrop-color` global variable has been replaced. <sup>[1](#version-10x-backdrop-replaced-css-variables)</sup>
+2. Theme classes (`ion-backdrop.md`, `ion-backdrop.ios`) are no longer supported. <sup>[2](#version-10x-backdrop-theme-classes)</sup>
+
+<h5 id="version-10x-backdrop-replaced-css-variables">Replaced CSS variables</h5>
+
+Use the new token structure for global styles, or the corresponding CSS variable for component-specific overrides:
+
+| Old (9.x) | New token (global) | New CSS variable (component-specific) |
+|---|---|---|
+| `--ion-backdrop-color` | `IonBackdrop.background` | `--ion-backdrop-background` |
+
+> [!NOTE]
+> `--ion-backdrop-color` was set on `:root`, and `--ion-backdrop-background` has no effect there. Set it on the backdrop of each overlay instead: `ion-alert ion-backdrop` for alert, action sheet and loading, and the `backdrop` part for menu, modal and popover (`ion-modal::part(backdrop)`).
+
+<h5 id="version-10x-backdrop-theme-classes">Theme classes</h5>
+
+Remove any instances that target the theme classes: `ion-backdrop.md`, `ion-backdrop.ios`.
+
 <h4 id="version-10x-button">Button</h4>
 
 - The `border-radius` of the `ios` and `md` button now defaults to `6px` and `999px` instead of `14px` and `4px`, respectively, in accordance with the iOS and Material Design 3 guidelines. To revert to the previous appearance, set the `shape` to `"soft"` for `md` and override the `--border-radius` CSS variable for `ios` to `14px`, or set it to a different value entirely.

core/api.txt

@@ -308,9 +308,9 @@ ion-backdrop,shadow
 ion-backdrop,prop,mode,"ios" | "md",undefined,false,false
 ion-backdrop,prop,stopPropagation,boolean,true,false,false
 ion-backdrop,prop,tappable,boolean,true,false,false
-ion-backdrop,prop,theme,"ios" | "md" | "ionic",undefined,false,false
 ion-backdrop,prop,visible,boolean,true,false,false
 ion-backdrop,event,ionBackdropTap,void,true
+ion-backdrop,css-prop,--ion-backdrop-background
 
 ion-badge,shadow
 ion-badge,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string & Record<never, never> | undefined,undefined,false,true

core/src/components.d.ts

@@ -469,10 +469,6 @@ export namespace Components {
           * @default true
          */
         "tappable": boolean;
-        /**
-          * The theme determines the visual appearance of the component.
-         */
-        "theme"?: "ios" | "md" | "ionic";
         /**
           * If `true`, the backdrop will be visible. This property controls whether or not the backdrop's default background is shown. It does not control whether or not the backdrop blocks interaction, and it does not override a custom background set on `ion-backdrop`.
           * @default true
@@ -6316,10 +6312,6 @@ declare namespace LocalJSX {
           * @default true
          */
         "tappable"?: boolean;
-        /**
-          * The theme determines the visual appearance of the component.
-         */
-        "theme"?: "ios" | "md" | "ionic";
         /**
           * If `true`, the backdrop will be visible. This property controls whether or not the backdrop's default background is shown. It does not control whether or not the backdrop blocks interaction, and it does not override a custom background set on `ion-backdrop`.
           * @default true

core/src/components/backdrop/_backdrop.docs.scss

@@ -0,0 +1,3 @@
+/**
+ * @prop --ion-backdrop-background: Background of the backdrop
+ */

core/src/components/backdrop/backdrop.interface.ts

@@ -0,0 +1,3 @@
+export interface IonBackdropRecipe {
+  background?: string;
+}

core/src/components/backdrop/backdrop.common.scss → core/src/components/backdrop/backdrop.scss

@@ -1,20 +1,28 @@
-@import "../../themes/mixins.scss";
+@use "../../themes/common.globals" as globals;
+@use "../../themes/mixins" as mixins;
+@use "./backdrop.docs";
 
 // Backdrop
 // --------------------------------------------------
 
 :host {
-  @include position(0, 0, 0, 0);
+  @include mixins.position(0, 0, 0, 0);
 
   display: block;
   position: absolute;
 
   transform: translateZ(0);
 
+  background-color: var(--ion-backdrop-background);
+
   contain: strict;
   cursor: pointer;
+
+  // Nearly transparent until an overlay or menu animation fades it in
   opacity: 0.01;
   touch-action: none;
+
+  z-index: globals.$z-index-backdrop;
 }
 
 :host(.backdrop-hide) {

core/src/components/backdrop/backdrop.tsx

@@ -1,19 +1,12 @@
 import type { ComponentInterface, EventEmitter } from '@stencil/core';
 import { Component, Event, Host, Listen, Prop, h } from '@stencil/core';
 
-import { getIonTheme } from '../../global/ionic-global';
-
 /**
  * @virtualProp {"ios" | "md"} mode - The mode determines the platform behaviors of the component.
- * @virtualProp {"ios" | "md" | "ionic"} theme - The theme determines the visual appearance of the component.
  */
 @Component({
   tag: 'ion-backdrop',
-  styleUrls: {
-    ios: 'backdrop.ios.scss',
-    md: 'backdrop.md.scss',
-    ionic: 'backdrop.ionic.scss',
-  },
+  styleUrl: 'backdrop.scss',
   shadow: true,
 })
 export class Backdrop implements ComponentInterface {
@@ -57,14 +50,14 @@ export class Backdrop implements ComponentInterface {
   }
 
   render() {
-    const theme = getIonTheme(this);
+    const { tappable, visible } = this;
+
     return (
       <Host
         aria-hidden="true"
         class={{
-          [theme]: true,
-          'backdrop-hide': !this.visible,
-          'backdrop-no-tappable': !this.tappable,
+          'backdrop-hide': !visible,
+          'backdrop-no-tappable': !tappable,
         }}
       ></Host>
     );

core/src/themes/common.globals.scss

@@ -20,3 +20,4 @@ $screen-breakpoints: (
 // Z-Index
 // --------------------------------------------------
 $z-index-page-container: 0;
+$z-index-backdrop: 2;

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

@@ -1,4 +1,4 @@
-import { currentColor, mix, dynamicFont, ionColor } from '../../utils/theme';
+import { rgba, currentColor, mix, dynamicFont, ionColor } from '../../utils/theme';
 import { defaultTheme as baseDefaultTheme } from '../base/default.tokens';
 import { colors as baseColors } from '../base/shared.tokens';
 import type { DefaultTheme } from '../themes.interfaces';
@@ -113,6 +113,10 @@ export const defaultTheme: DefaultTheme = {
   },
 
   components: {
+    IonBackdrop: {
+      background: rgba('19, 21, 24', 0.7),
+    },
+
     IonBadge: {
       // Hues
       hue: {

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

@@ -123,6 +123,10 @@ export const defaultTheme: DefaultTheme = {
   },
 
   components: {
+    IonBackdrop: {
+      background: baseColors.black,
+    },
+
     IonBadge: {
       font: {
         family: 'var(--ion-font-family)',

core/src/themes/md/default.tokens.ts

@@ -117,6 +117,10 @@ export const defaultTheme: DefaultTheme = {
   },
 
   components: {
+    IonBackdrop: {
+      background: baseColors.black,
+    },
+
     IonBadge: {
       font: {
         family: 'var(--ion-font-family)',

core/src/themes/native/native.globals.scss

@@ -68,7 +68,6 @@ $z-index-toolbar: 10;
 $z-index-toolbar-background: -1;
 $z-index-toolbar-buttons: 99;
 
-$z-index-backdrop: 2;
 $z-index-overlay-wrapper: 10;
 
 $z-index-item-options: 1;

core/src/themes/native/native.theme.default.ios.scss

@@ -6,7 +6,6 @@
 
 // iOS General Colors
 // --------------------------------------------------
-$backdrop-ios-color: var(--ion-backdrop-color, #000);
 $overlay-ios-background-color: var(--ion-overlay-background-color, var(--ion-background-color-step-100, #f9f9f9));
 
 // iOS Tabs & Tab bar

core/src/themes/native/native.theme.default.md.scss

@@ -6,7 +6,6 @@
 
 // Material Design General Colors
 // --------------------------------------------------
-$backdrop-md-color: var(--ion-backdrop-color, #000);
 $border-md-color: var(--ion-border-color, var(--ion-background-color-step-150, #c1c4cd));
 $overlay-md-background-color: var(--ion-overlay-background-color, var(--ion-background-color, #fff));
 

core/src/themes/native/test/css-variables/css/oceanic.css

@@ -75,7 +75,6 @@
   --ion-color-dark-tint: #343d46;
 
   /* Component Colors */
-  --ion-backdrop-color: #1b2b34;
   --ion-overlay-background-color: #142129;
 
   --ion-border-color: #1b2b34;
@@ -138,3 +137,9 @@
   --ion-text-color-step-950: #324048;
   --ion-text-color-step-1000: #26363e;
 }
+
+ion-action-sheet ion-backdrop,
+ion-alert ion-backdrop,
+ion-loading ion-backdrop {
+  --ion-backdrop-background: #1b2b34;
+}

core/src/themes/themes.interfaces.ts

@@ -1,3 +1,4 @@
+import type { IonBackdropRecipe } from '../components/backdrop/backdrop.interface';
 import type { IonBadgeConfig, IonBadgeRecipe } from '../components/badge/badge.interface';
 import type { IonChipConfig, IonChipRecipe } from '../components/chip/chip.interface';
 import type { IonColRecipe } from '../components/col/col.interface';
@@ -297,6 +298,7 @@ export type DefaultTheme = BaseTheme & {
 
 type Components = {
   IonAvatar?: any;
+  IonBackdrop?: IonBackdropRecipe;
   IonBadge?: IonBadgeRecipe;
   IonChip?: IonChipRecipe;
   IonCol?: IonColRecipe;