Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(AppShell): add variant prop for nav/content background styles (#597)

Cindy Zhang9237ea58bcd1
diff --git a/packages/cli/src/commands/theme.mjs b/packages/cli/src/commands/theme.mjs
index e2066bf268..77d807a99e 100644
--- a/packages/cli/src/commands/theme.mjs
+++ b/packages/cli/src/commands/theme.mjs
@@ -130,7 +130,6 @@ function deriveColorPalette({accent, positive, negative, warning, mode}) {
// Surface variants
'--color-card': ld('#FFFFFF', '#1F1F22'),
'--color-popover': ld('#FFFFFF', '#28292C'),
- '--color-navbar': ld('#FFFFFF', '#1F1F22'),
// Status
'--color-positive': ld(positive, positive),
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index 686490867e..6b7ccd9c39 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -18,7 +18,12 @@
import {useCallback, useEffect, useRef, useState, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
-import {colorVars, fontWeightVars, textSizeVars} from '../theme/tokens.stylex';
+import {
+ colorVars,
+ fontWeightVars,
+ radiusVars,
+ textSizeVars,
+} from '../theme/tokens.stylex';
import {XDSLayout} from '../Layout/XDSLayout';
import {XDSLayoutHeader} from '../Layout/XDSLayoutHeader';
import {XDSLayoutPanel} from '../Layout/XDSLayoutPanel';
@@ -54,16 +59,28 @@ const MAIN_CONTENT_ID = 'xds-app-shell-main';
*/
export type XDSAppShellBreakpoint = 'sm' | 'md' | 'lg' | 'none';
+/**
+ * Navigation background style:
+ * - `wash`: Nav areas use wash background, no dividers
+ * - `surface`: Nav areas use surface background, no dividers
+ * - `section`: Dividers between nav and content (classic look)
+ * - `elevated`: Wash nav background with elevated surface content + border radius
+ * @default 'section'
+ */
+export type XDSAppShellVariant = 'wash' | 'surface' | 'section' | 'elevated';
+
export interface XDSAppShellProps {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLDivElement>;
/**
- * Background color of the shell.
- * - `wash`: Page-level background — subtle gray in light, near-black in dark
- * - `surface`: Card/panel background — white in light, dark gray in dark
- * @default 'surface'
+ * Navigation background style controlling how nav areas contrast with content.
+ * - `wash`: Nav uses wash background, no dividers
+ * - `surface`: Nav uses surface background, no dividers
+ * - `section`: Dividers between nav and content (classic look)
+ * - `elevated`: Wash nav with elevated surface content area + border radius
+ * @default 'section'
*/
- background?: 'wash' | 'surface';
+ variant?: XDSAppShellVariant;
/**
* Optional banner slot for system-wide announcements.
@@ -172,15 +189,20 @@ const styles = stylex.create({
flexDirection: 'column',
position: 'relative',
},
- rootBgWash: {
+ variantWash: {
backgroundColor: colorVars['--color-wash'],
},
- rootBgSurface: {
+ variantSurface: {
+ backgroundColor: colorVars['--color-surface'],
+ },
+ variantSection: {
backgroundColor: colorVars['--color-surface'],
},
+ variantElevated: {
+ backgroundColor: colorVars['--color-wash'],
+ },
rootFill: {
height: '100dvh',
- overflow: 'hidden',
},
rootAuto: {
minHeight: '100dvh',
@@ -236,6 +258,37 @@ const styles = stylex.create({
fontWeight: fontWeightVars['--font-weight-semibold'],
fontSize: textSizeVars['--text-base'],
},
+
+ elevatedBackdrop: {
+ position: 'absolute',
+ inset: 0,
+ backgroundColor: colorVars['--color-surface'],
+ borderStartStartRadius: radiusVars['--radius-page'],
+ pointerEvents: 'none',
+ },
+ elevatedContentWrapper: {
+ position: 'relative',
+ display: 'flex',
+ flex: 1,
+ minHeight: 0,
+ height: '100%',
+ },
+ contentBgSurface: {
+ backgroundColor: colorVars['--color-surface'],
+ },
+ contentBgWash: {
+ backgroundColor: colorVars['--color-wash'],
+ },
+ contentBgTransparent: {
+ backgroundColor: 'transparent',
+ isolation: 'isolate',
+ },
+ navAreaWash: {
+ backgroundColor: colorVars['--color-wash'],
+ },
+ navAreaSurface: {
+ backgroundColor: colorVars['--color-surface'],
+ },
banner: {
flexShrink: 0,
},
@@ -288,7 +341,7 @@ const styles = stylex.create({
* ```
*/
export function XDSAppShell({
- background = 'surface',
+ variant = 'section',
banner,
children,
'data-testid': dataTestId,
@@ -322,10 +375,28 @@ export function XDSAppShell({
const isFill = height === 'fill';
const isAuto = height === 'auto';
+
+ // Nav style derived values
+ const hasBanner = banner != null;
+ const hasTopNav = topNav != null;
const hasSideNav = sideNav != null;
const hasMobileNav = mobileNav != null;
- const hasTopNav = topNav != null;
- const hasBanner = banner != null;
+ const navHasDividers = variant === 'section';
+ const isElevated = variant === 'elevated';
+ const navAreaStyle =
+ variant === 'wash' || variant === 'elevated'
+ ? styles.navAreaWash
+ : variant === 'surface'
+ ? styles.navAreaSurface
+ : undefined;
+ const contentAreaStyle =
+ variant === 'wash'
+ ? styles.contentBgWash
+ : variant === 'elevated' && hasTopNav && hasSideNav
+ ? styles.contentBgTransparent
+ : variant === 'surface' || variant === 'elevated'
+ ? styles.contentBgSurface
+ : undefined;
// =========================================================================
// Header height measurement for sticky sideNav offset (auto mode)
@@ -427,7 +498,10 @@ export function XDSAppShell({
// =========================================================================
const headerInner =
hasTopNav || hasBanner ? (
- <XDSLayoutHeader isFullBleed hasDivider={hasTopNav}>
+ <XDSLayoutHeader
+ isFullBleed
+ hasDivider={navHasDividers && hasTopNav}
+ xstyle={navAreaStyle}>
{hasBanner && <div {...stylex.props(styles.banner)}>{banner}</div>}
{hasTopNav && topNav}
</XDSLayoutHeader>
@@ -451,11 +525,12 @@ export function XDSAppShell({
const sideNavPanel = showSideNavInline ? (
<XDSLayoutPanel
isFullBleed
- hasDivider
+ hasDivider={navHasDividers}
width={sideNavWidth}
role="navigation"
label="Application navigation"
- isScrollable={isFill}>
+ isScrollable={isFill}
+ xstyle={navAreaStyle}>
{sideNav}
</XDSLayoutPanel>
) : undefined;
@@ -472,16 +547,28 @@ export function XDSAppShell({
// =========================================================================
// Build main content
// =========================================================================
- const mainContent = (
+ const shouldElevateWithCorner = isElevated && hasTopNav && showSideNavInline;
+
+ const mainInner = (
<XDSLayoutContent
isFullBleed
role="main"
id={MAIN_CONTENT_ID}
- isScrollable={isFill}>
+ isScrollable={isFill}
+ xstyle={contentAreaStyle}>
{children}
</XDSLayoutContent>
);
+ const mainContent = shouldElevateWithCorner ? (
+ <div {...stylex.props(styles.elevatedContentWrapper)}>
+ <div {...stylex.props(styles.elevatedBackdrop)} />
+ {mainInner}
+ </div>
+ ) : (
+ mainInner
+ );
+
// =========================================================================
// Render
//
@@ -493,10 +580,16 @@ export function XDSAppShell({
ref={setShellRef}
data-testid={dataTestId}
{...mergeProps(
- xdsClassName('app-shell', {background, height}),
+ xdsClassName('app-shell', {height, variant}),
stylex.props(
styles.root,
- background === 'wash' ? styles.rootBgWash : styles.rootBgSurface,
+ variant === 'wash'
+ ? styles.variantWash
+ : variant === 'surface'
+ ? styles.variantSurface
+ : variant === 'section'
+ ? styles.variantSection
+ : styles.variantElevated,
isFill ? styles.rootFill : styles.rootAuto,
xstyle,
),
@@ -512,8 +605,8 @@ export function XDSAppShell({
</a>
<XDSLayout
- height={height}
isFullBleed
+ height={height}
header={headerContent}
start={sideNavContent}
content={mainContent}
diff --git a/packages/core/src/AppShell/index.ts b/packages/core/src/AppShell/index.ts
index 9ac9b90405..c43da02c7d 100644
--- a/packages/core/src/AppShell/index.ts
+++ b/packages/core/src/AppShell/index.ts
@@ -8,4 +8,8 @@
*/
export {XDSAppShell} from './XDSAppShell';
-export type {XDSAppShellProps, XDSAppShellBreakpoint} from './XDSAppShell';
+export type {
+ XDSAppShellProps,
+ XDSAppShellBreakpoint,
+ XDSAppShellVariant,
+} from './XDSAppShell';
diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsx
index 6dc55ef57b..f5afcedee7 100644
--- a/packages/core/src/SideNav/XDSSideNav.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.tsx
@@ -32,7 +32,7 @@ const styles = stylex.create({
display: 'flex',
flexDirection: 'column',
height: '100%',
- backgroundColor: colorVars['--color-surface'],
+ backgroundColor: 'inherit',
boxSizing: 'border-box',
overflow: 'hidden',
},
@@ -43,7 +43,7 @@ const styles = stylex.create({
position: 'sticky',
top: 0,
zIndex: 1,
- backgroundColor: colorVars['--color-surface'],
+ backgroundColor: 'inherit',
},
topContent: {
paddingInline: spacingVars['--spacing-2'],
@@ -61,7 +61,7 @@ const styles = stylex.create({
marginTop: 'auto',
position: 'sticky',
bottom: 0,
- backgroundColor: colorVars['--color-surface'],
+ backgroundColor: 'inherit',
},
footer: {
paddingInline: spacingVars['--spacing-2'],
diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjs
index 76cf00d30b..6246742d01 100644
--- a/packages/core/src/TopNav/TopNav.doc.mjs
+++ b/packages/core/src/TopNav/TopNav.doc.mjs
@@ -135,7 +135,6 @@ export const docs = {
'Tab to navigate between items; Escape closes XDSTopNavMegaMenu panels',
notes: [
'Default height is 48px (--spacing-12) with 16px horizontal padding',
- 'Uses --color-navbar token for background (defaults to white)',
'Without centerContent: heading and startContent grow to push endContent right (flex layout)',
'With centerContent: switches to CSS grid (gridTemplateColumns: 1fr auto 1fr) — the right column is always rendered even when endContent is absent to maintain the three-column structure',
'Positioning (sticky/fixed) is handled by the layout system (e.g. XDSAppShell), not TopNav itself',
diff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsx
index cc704f1300..25517db289 100644
--- a/packages/core/src/TopNav/XDSTopNav.tsx
+++ b/packages/core/src/TopNav/XDSTopNav.tsx
@@ -29,7 +29,6 @@ const styles = stylex.create({
width: '100%',
height: spacingVars['--spacing-12'],
paddingInline: spacingVars['--spacing-4'],
- backgroundColor: colorVars['--color-navbar'],
boxSizing: 'border-box',
// Publish inline padding for edge compensation (ghost buttons at edges).
// Uses --container-padding-inline (not --container-padding) because TopNav
diff --git a/packages/core/src/theme/tokens.stylex.ts b/packages/core/src/theme/tokens.stylex.ts
index ee7c977dd6..a0234150bc 100644
--- a/packages/core/src/theme/tokens.stylex.ts
+++ b/packages/core/src/theme/tokens.stylex.ts
@@ -48,7 +48,6 @@ export const colorDefaults = {
// Surface variants
'--color-card': 'light-dark(#FFFFFF, #1F1F22)',
'--color-popover': 'light-dark(#FFFFFF, #28292C)',
- '--color-navbar': 'light-dark(#FFFFFF, #1F1F22)',
// Status/Sentiment
'--color-positive': 'light-dark(#0D8626, #0D8626)',
@@ -192,6 +191,7 @@ export const radiusDefaults = {
'--radius-element': '8px',
'--radius-content': '4px',
'--radius-inner': '0px',
+ '--radius-page': '20px',
} as const;
/** @deprecated Use radiusDefaults */
diff --git a/packages/themes/neutral/src/neutralTheme.ts b/packages/themes/neutral/src/neutralTheme.ts
index 0a4db0e1f7..eea6700640 100644
--- a/packages/themes/neutral/src/neutralTheme.ts
+++ b/packages/themes/neutral/src/neutralTheme.ts
@@ -54,7 +54,6 @@ export const neutralTheme = defineTheme({
// Surface variants
'--color-card': ['oklch(1 0 0)', 'oklch(0.205 0 0)'],
'--color-popover': ['oklch(1 0 0)', 'oklch(0.269 0 0)'],
- '--color-navbar': ['oklch(0.985 0 0)', 'oklch(0.205 0 0)'],
// Status/Sentiment
'--color-positive': ['oklch(0.6 0.15 145)', 'oklch(0.7 0.15 145)'],