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.mjsindex 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.tsxindex 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 ? (<XDSLayoutPanelisFullBleed- 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 = (<XDSLayoutContentisFullBleedrole="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.tsindex 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.tsxindex 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.mjsindex 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.tsxindex 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 TopNavdiff --git a/packages/core/src/theme/tokens.stylex.ts b/packages/core/src/theme/tokens.stylex.tsindex 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.tsindex 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)'],