ciampo · Aug 20, 2026 · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/boot/CHANGELOG.md b/packages/boot/CHANGELOG.md
@@ -23,6 +23,10 @@
 
 -   Remove `editLink` from a route's canvas data. Register the post type's `edit` path with `registerEntityLinks` instead ([#81590](https://github.com/WordPress/gutenberg/pull/81590)).
 
+### Internal
+
+-   Migrate Boot styles to CSS Modules and encapsulate its internal DOM classes ([#81756](https://github.com/WordPress/gutenberg/pull/81756)).
+
 ## 0.20.0 (2026-08-12)
 
 ### Bug Fixes

diff --git a/packages/boot/README.md b/packages/boot/README.md
@@ -55,6 +55,10 @@ Both functions follow the same startup sequence:
 2. Run the page's init modules (see below).
 3. Render the application into `mountId`.
 
+Boot's internal shell is private. Consumers can style the mount element and
+their own route content. Boot does not provide stable styling hooks or
+replacement hooks for its internal layout, navigation, and surface elements.
+
 ## Init modules
 
 Init modules are script modules that run a one-time setup step at page startup, after menu items and routes are registered and before the app renders. They are useful for tasks that cannot be expressed in the page's static PHP configuration, such as assigning menu-item icons or registering core-data entities.

diff --git a/packages/boot/package.json b/packages/boot/package.json
@@ -61,6 +61,7 @@
 		"@wordpress/primitives": "file:../primitives",
 		"@wordpress/private-apis": "file:../private-apis",
 		"@wordpress/route": "file:../route",
+		"@wordpress/style-runtime": "file:../style-runtime",
 		"@wordpress/theme": "file:../theme",
 		"@wordpress/ui": "file:../ui",
 		"@wordpress/url": "file:../url",

diff --git a/packages/boot/src/components/app/router.tsx b/packages/boot/src/components/app/router.tsx
@@ -9,6 +9,7 @@ import {
 import { resolveSelect } from '@wordpress/data';
 import { store as coreStore } from '@wordpress/core-data';
 import Root from '../root';
+import styles from '../root/style.module.scss';
 import ErrorBoundary from '../error-boundary';
 import type { Route, RouteConfig, RouteLoaderContext } from '../../store/types';
 import { unlock } from '../../lock-unlock';
@@ -27,7 +28,7 @@ const {
 // Not found component
 function NotFoundComponent() {
 	return (
-		<div className="boot-layout__stage">
+		<div className={ styles.stage }>
 			<Page title={ __( 'Route not found' ) } hasPadding>
 				{ __( "The page you're looking for does not exist" ) }
 			</Page>
@@ -129,14 +130,14 @@ function createRouteFromDefinition( route: Route, parentRoute: AnyRoute ) {
 				return (
 					<>
 						{ Stage && showStage && (
-							<div className="boot-layout__stage">
+							<div className={ styles.stage }>
 								<ErrorBoundary>
 									<Stage />
 								</ErrorBoundary>
 							</div>
 						) }
 						{ Inspector && showInspector && (
-							<div className="boot-layout__inspector">
+							<div className={ styles.inspector }>
 								<ErrorBoundary>
 									<Inspector />
 								</ErrorBoundary>

diff --git a/packages/boot/src/components/error-boundary/index.tsx b/packages/boot/src/components/error-boundary/index.tsx
@@ -5,7 +5,7 @@ import { Button } from '@wordpress/components';
 import { EmptyState } from '@wordpress/ui';
 import { useCopyToClipboard } from '@wordpress/compose';
 import { caution } from '@wordpress/icons';
-import './style.scss';
+import styles from './style.module.scss';
 
 interface Props {
 	children: ReactNode;
@@ -50,7 +50,7 @@ export default class ErrorBoundary extends Component< Props, State > {
 		}
 
 		return (
-			<div className="boot-error-boundary">
+			<div className={ styles[ 'error-boundary' ] }>
 				<EmptyState.Root>
 					<EmptyState.Icon icon={ caution } />
 					<EmptyState.Title>

diff --git a/.../src/components/error-boundary/style.scss → ...mponents/error-boundary/style.module.scss b/.../src/components/error-boundary/style.scss → ...mponents/error-boundary/style.module.scss
@@ -3,7 +3,7 @@
 // The surfaces this sits in are sized by their container, so fill the height
 // available and centre the message in it rather than leaving it at the top of
 // an otherwise empty area.
-.boot-error-boundary {
+.error-boundary {
 	display: flex;
 	align-items: center;
 	justify-content: center;

diff --git a/packages/boot/src/components/navigation/drilldown-item/index.tsx b/packages/boot/src/components/navigation/drilldown-item/index.tsx
@@ -10,6 +10,7 @@ import { isRTL } from '@wordpress/i18n';
 import { chevronRightSmall, chevronLeftSmall } from '@wordpress/icons';
 import { wrapIcon } from '../items';
 import type { IconType } from '../../../store/types';
+import styles from '../navigation-item/style.module.scss';
 
 interface DrilldownItemProps {
 	/**
@@ -59,7 +60,7 @@ export default function DrilldownItem( {
 
 	return (
 		<Item
-			className={ clsx( 'boot-navigation-item', className ) }
+			className={ clsx( styles.item, className ) }
 			onClick={ handleClick }
 		>
 			<HStack

diff --git a/packages/boot/src/components/navigation/dropdown-item/index.tsx b/packages/boot/src/components/navigation/dropdown-item/index.tsx
@@ -15,7 +15,8 @@ import { STORE_NAME } from '../../../store';
 import NavigationItem from '../navigation-item';
 import { wrapIcon } from '../items';
 import type { IconType, MenuItem } from '../../../store/types';
-import './style.scss';
+import navigationItemStyles from '../navigation-item/style.module.scss';
+import styles from './style.module.scss';
 
 const ANIMATION_DURATION = 0.2;
 
@@ -67,9 +68,9 @@ export default function DropdownItem( {
 	const items = menuItems.filter( ( item ) => item.parent === id );
 	const disableMotion = useReducedMotion();
 	return (
-		<div className="boot-dropdown-item">
+		<div className={ styles.dropdown }>
 			<Item
-				className={ clsx( 'boot-navigation-item', className ) }
+				className={ clsx( navigationItemStyles.item, className ) }
 				onClick={ ( e ) => {
 					e.preventDefault();
 					e.stopPropagation();
@@ -86,8 +87,8 @@ export default function DropdownItem( {
 					<FlexBlock>{ children }</FlexBlock>
 					<WCIcon
 						icon={ chevronDownSmall }
-						className={ clsx( 'boot-dropdown-item__chevron', {
-							'is-up': isExpanded,
+						className={ clsx( styles.chevron, {
+							[ styles[ 'is-up' ] ]: isExpanded,
 						} ) }
 					/>
 				</HStack>
@@ -103,11 +104,14 @@ export default function DropdownItem( {
 							duration: disableMotion ? 0 : ANIMATION_DURATION,
 							ease: 'easeOut',
 						} }
-						className="boot-dropdown-item__children"
+						className={ styles[ 'dropdown-children' ] }
 					>
 						{ items.map( ( item, index ) => (
 							<NavigationItem
 								key={ index }
+								className={
+									navigationItemStyles[ 'is-compact' ]
+								}
 								to={ item.to }
 								shouldShowPlaceholder={ false }
 							>

diff --git a/...nents/navigation/dropdown-item/style.scss → ...avigation/dropdown-item/style.module.scss b/...nents/navigation/dropdown-item/style.scss → ...avigation/dropdown-item/style.module.scss
@@ -1,6 +1,10 @@
 @use "@wordpress/base-styles/variables";
 
-.boot-dropdown-item__children {
+.dropdown {
+	display: block;
+}
+
+.dropdown-children {
 	display: flex;
 	flex-direction: column;
 
@@ -18,6 +22,6 @@
 	overflow: hidden;
 }
 
-.boot-dropdown-item__chevron.is-up {
+.chevron.is-up {
 	transform: rotate(180deg);
 }
diff --git a/packages/boot/src/components/navigation/index.tsx b/packages/boot/src/components/navigation/index.tsx
@@ -72,7 +72,6 @@ function Navigation() {
 								<DropdownItem
 									key={ item.id }
 									id={ item.id }
-									className="boot-navigation-item"
 									icon={ item.icon }
 									shouldShowPlaceholder={ hasRealIcons }
 									isExpanded={ parentDropdownId === item.id }

diff --git a/packages/boot/src/components/navigation/navigation-item/index.tsx b/packages/boot/src/components/navigation/navigation-item/index.tsx
@@ -8,7 +8,7 @@ import {
 import RouterLinkItem from '../router-link-item';
 import { wrapIcon } from '../items';
 import type { IconType } from '../../../store/types';
-import './style.scss';
+import styles from './style.module.scss';
 
 interface NavigationItemProps {
 	/**
@@ -58,18 +58,15 @@ export default function NavigationItem( {
 			<Item
 				as="a"
 				href={ to }
-				className={ clsx( 'boot-navigation-item', className ) }
+				className={ clsx( styles.item, className ) }
 			>
 				{ content }
 			</Item>
 		);
 	}
 
 	return (
-		<RouterLinkItem
-			to={ to }
-			className={ clsx( 'boot-navigation-item', className ) }
-		>
+		<RouterLinkItem to={ to } className={ clsx( styles.item, className ) }>
 			{ content }
 		</RouterLinkItem>
 	);

diff --git a/...nts/navigation/navigation-item/style.scss → ...igation/navigation-item/style.module.scss b/...nts/navigation/navigation-item/style.scss → ...igation/navigation-item/style.module.scss
@@ -1,7 +1,8 @@
 @use "@wordpress/base-styles/variables";
 @use "@wordpress/base-styles/mixins";
 
-.boot-navigation-item.components-item {
+// Override Item's default styles without depending on its class names.
+.item.item {
 	color: var(--wpds-color-foreground-interactive-neutral);
 	padding-inline: variables.$grid-unit-05;
 	padding-block: 0;
@@ -14,29 +15,21 @@
 	align-items: center;
 	@include mixins.body-medium();
 
-	.boot-dropdown-item__children & {
-		min-height: variables.$grid-unit-30;
-	}
-
 	// Rounded focus ring
 	border-radius: var(--wpds-border-radius-sm);
 
-	&.active,
 	&:hover,
 	&:focus,
 	&[aria-current="true"] {
 		color: var(--wpds-color-foreground-interactive-brand-active);
 	}
 
-	&.active {
-		font-weight: var(--wpds-typography-font-weight-emphasis);
-	}
-
 	svg:last-child {
 		padding: variables.$grid-unit-05;
 	}
 
-	&[aria-current="true"] {
+	&[aria-current="page"],
+	&[data-status="active"] {
 		color: var(--wpds-color-foreground-interactive-brand-active);
 		font-weight: var(--wpds-typography-font-weight-emphasis);
 	}
@@ -45,8 +38,8 @@
 	&:focus-visible {
 		transform: translateZ(0);
 	}
+}
 
-	&.with-suffix {
-		padding-right: variables.$grid-unit-20;
-	}
+.item.is-compact {
+	min-height: variables.$grid-unit-30;
 }
diff --git a/packages/boot/src/components/navigation/navigation-screen/index.tsx b/packages/boot/src/components/navigation/navigation-screen/index.tsx
@@ -9,7 +9,7 @@ import {
 import { isRTL, __ } from '@wordpress/i18n';
 import { chevronRight, chevronLeft } from '@wordpress/icons';
 import { useReducedMotion } from '@wordpress/compose';
-import './style.scss';
+import styles from './style.module.scss';
 
 const ANIMATION_DURATION = 0.3;
 const slideVariants = {
@@ -66,7 +66,7 @@ export default function NavigationScreen( {
 
 	return (
 		<div
-			className="boot-navigation-screen"
+			className={ styles.screen }
 			style={ {
 				overflow: 'hidden',
 				position: 'relative',
@@ -94,10 +94,7 @@ export default function NavigationScreen( {
 						gridRow: '1',
 					} }
 				>
-					<HStack
-						spacing={ 2 }
-						className="boot-navigation-screen__title-icon"
-					>
+					<HStack spacing={ 2 } className={ styles[ 'title-icon' ] }>
 						{ ! isRoot && (
 							<Button
 								ref={ backButtonRef }
@@ -109,24 +106,18 @@ export default function NavigationScreen( {
 							/>
 						) }
 						<Heading
-							className="boot-navigation-screen__title"
+							className={ styles.title }
 							level={ 1 }
 							size="15px"
 						>
 							{ title }
 						</Heading>
 						{ actions && (
-							<div className="boot-navigation-screen__actions">
-								{ actions }
-							</div>
+							<div className={ styles.actions }>{ actions }</div>
 						) }
 					</HStack>
 
-					{ description && (
-						<div className="boot-navigation-screen__description">
-							{ description }
-						</div>
-					) }
+					{ description && <div>{ description }</div> }
 
 					{ content }
 				</motion.div>

diff --git a/...s/navigation/navigation-screen/style.scss → ...ation/navigation-screen/style.module.scss b/...s/navigation/navigation-screen/style.scss → ...ation/navigation-screen/style.module.scss
@@ -1,34 +1,35 @@
 @use "@wordpress/base-styles/variables";
 
-.boot-navigation-screen {
+.screen {
 	// Avoid cutting off focus ring of the last menu item
 	padding-block-end: variables.$grid-unit-05;
 }
 
-.boot-navigation-screen .components-text {
+.screen :global(.components-text) {
 	color: var(--wpds-color-foreground-content-neutral);
 }
 
-.boot-navigation-screen__title-icon {
+.title-icon {
 	position: sticky;
 	top: 0;
-	padding:
-		variables.$grid-unit-15 variables.$grid-unit-20
-		variables.$grid-unit-10 variables.$grid-unit-20;
+	padding-block-start: variables.$grid-unit-15;
+	padding-inline-end: variables.$grid-unit-20;
+	padding-block-end: variables.$grid-unit-10;
+	padding-inline-start: variables.$grid-unit-20;
 }
 
-.boot-navigation-screen__title {
+.title {
 	flex-grow: 1;
 	overflow-wrap: break-word;
 
 	&#{&},
-	&#{&} .boot-navigation-screen__title {
+	&#{&} .title {
 		line-height: variables.$font-line-height-x-large;
 		color: var(--wpds-color-foreground-content-neutral);
 	}
 }
 
-.boot-navigation-screen__actions {
+.actions {
 	display: flex;
 	flex-shrink: 0;
 }