An open source design system that's fully customizable and agent ready
TypeScript
feat(core): edge compensation pattern via CSS custom properties (#410)
Cindy Zhangce7b4111fb09
diff --git a/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-All-Features-Combined.png b/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-All-Features-Combined.pngnew file mode 100644index 0000000000..27943d6d08Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-All-Features-Combined.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-Collapsible-Content-Collapsed-.png b/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-Collapsible-Content-Collapsed-.pngnew file mode 100644index 0000000000..1e0d12d681Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-Collapsible-Content-Collapsed-.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-Collapsible-Content-Expanded-.png b/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-Collapsible-Content-Expanded-.pngnew file mode 100644index 0000000000..fdc45d7805Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-Collapsible-Content-Expanded-.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-Dismissable-With-Callback.png b/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-Dismissable-With-Callback.pngnew file mode 100644index 0000000000..157feb4dd6Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-Dismissable-With-Callback.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Core-XDSButton-Icon-And-End-Slot.png b/e2e/visual-regression.spec.ts-snapshots/Core-XDSButton-Icon-And-End-Slot.pngnew file mode 100644index 0000000000..036dd6dda1Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Core-XDSButton-Icon-And-End-Slot.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Core-XDSButton-With-End-Slot.png b/e2e/visual-regression.spec.ts-snapshots/Core-XDSButton-With-End-Slot.pngnew file mode 100644index 0000000000..290eb64089Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Core-XDSButton-With-End-Slot.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSHStack-Wrapping.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSHStack-Wrapping.pngnew file mode 100644index 0000000000..74fc95c0b2Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSHStack-Wrapping.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Default.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Default.pngnew file mode 100644index 0000000000..14ca572bdbBinary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Default.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Header-Layout.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Header-Layout.pngnew file mode 100644index 0000000000..2d604cbf83Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Header-Layout.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Horizontal-Alignments.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Horizontal-Alignments.pngnew file mode 100644index 0000000000..3cf64e2343Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Horizontal-Alignments.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Horizontal.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Horizontal.pngnew file mode 100644index 0000000000..74706c40a0Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Horizontal.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Page-Layout.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Page-Layout.pngnew file mode 100644index 0000000000..33da1447afBinary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Page-Layout.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Sidebar-Layout.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Sidebar-Layout.pngnew file mode 100644index 0000000000..b4d87c8deeBinary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Sidebar-Layout.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Stack-Item-Cross-Align-Self.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Stack-Item-Cross-Align-Self.pngnew file mode 100644index 0000000000..7a4f371a2dBinary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Stack-Item-Cross-Align-Self.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Stack-Item-Equal-Fill.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Stack-Item-Equal-Fill.pngnew file mode 100644index 0000000000..7ed3e9a0ccBinary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Stack-Item-Equal-Fill.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Stack-Item-Fill-Size.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Stack-Item-Fill-Size.pngnew file mode 100644index 0000000000..1f282adeaaBinary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Stack-Item-Fill-Size.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Vertical-Alignments.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Vertical-Alignments.pngnew file mode 100644index 0000000000..1b6d12aeccBinary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Vertical-Alignments.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Vertical.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Vertical.pngnew file mode 100644index 0000000000..8df569c922Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Vertical.png differdiff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Wrapping.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Wrapping.pngnew file mode 100644index 0000000000..74fc95c0b2Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Wrapping.png differdiff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsxindex f31dbcd297..c4dea19f28 100644--- a/packages/core/src/Banner/XDSBanner.tsx+++ b/packages/core/src/Banner/XDSBanner.tsx@@ -30,6 +30,7 @@ import {} from '@heroicons/react/24/solid';import {XDSButton} from '../Button';import {XDSIcon} from '../Icon';+import {edgeSignals} from '../Layout/edgeCompensation.stylex';import {colorVars,spacingVars,@@ -177,6 +178,10 @@ const styles = stylex.create({gap: spacingVars['--spacing-2'],paddingBlock: spacingVars['--spacing-3'],paddingInline: spacingVars['--spacing-4'],+ // Publish inline padding for edge compensation (ghost buttons at edges).+ // Uses --container-padding-inline (not --container-padding) because Banner+ // has different block padding (spacing-3) vs inline padding (spacing-4).+ '--container-padding-inline': spacingVars['--spacing-4'],},// When there's only a title (no description) and actions, center everything verticallyheaderCentered: {@@ -218,9 +223,8 @@ const styles = stylex.create({flexShrink: 0,marginInlineStart: 'auto',},- dismissButton: {- margin: `calc(-1 * ${spacingVars['--spacing-2']})`,- },+ // dismissButton negative margin removed — edge compensation handles this+ // automatically via --edge-end signal on the endArea// Content area — card background for additional content below the headercontentArea: {backgroundColor: colorVars['--color-card'],@@ -392,7 +396,7 @@ export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>()}</div>{showEndArea && (- <div {...stylex.props(styles.endArea)}>+ <div {...stylex.props(styles.endArea, edgeSignals.end)}>{endButton}{hasChildren && (<XDSButton@@ -412,16 +416,14 @@ export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>(/>)}{isDismissable && (- <div {...stylex.props(styles.dismissButton)}>- <XDSButton- variant="ghost"- size="sm"- label="Dismiss"- tooltip="Dismiss"- icon={<XDSIcon icon="close" size="sm" color="inherit" />}- onClick={handleDismiss}- />- </div>+ <XDSButton+ variant="ghost"+ size="sm"+ label="Dismiss"+ tooltip="Dismiss"+ icon={<XDSIcon icon="close" size="sm" color="inherit" />}+ onClick={handleDismiss}+ />)}</div>)}diff --git a/packages/core/src/Button/XDSButton.tsx b/packages/core/src/Button/XDSButton.tsxindex 889b036095..8b4a0303ab 100644--- a/packages/core/src/Button/XDSButton.tsx+++ b/packages/core/src/Button/XDSButton.tsx@@ -37,6 +37,7 @@ import {XDSTooltip} from '../Layer/XDSTooltip';import {XDSSpinner} from '../Spinner';import type {XDSIconProps} from '../Icon/XDSIcon';import type {XDSBadgeProps} from '../Badge/XDSBadge';+import {edgeCompensation} from '../Layout/edgeCompensation.stylex';/*** Base button styles@@ -279,6 +280,21 @@ const loadingStyles = stylex.create({},});+/**+ * Edge compensation: publish the component's own inline padding so the+ * compensation formula can read it. This is separate from the base padding+ * styles so themes can override button padding independently and+ * compensation stays in sync.+ */+const edgeCompStyles = stylex.create({+ paddingInline2: {+ '--component-padding-inline': spacingVars['--spacing-2'],+ },+ paddingInline3: {+ '--component-padding-inline': spacingVars['--spacing-3'],+ },+});+/*** A versatile button component with multiple variants.*@@ -342,6 +358,18 @@ export const XDSButton = forwardRef<HTMLButtonElement, XDSButtonProps>(props.onClick?.(e);};+ // Ghost buttons opt into edge compensation — they self-adjust margins+ // when placed at container edges (e.g., TopNav endContent).+ // The component publishes its own inline padding via --component-padding-inline+ // so the compensation formula stays theme-safe.+ const isFlat = variant === 'ghost';+ const edgeCompStyle = isFlat ? edgeCompensation.self : null;+ const edgePaddingSignal = isFlat+ ? isIconOnly+ ? edgeCompStyles.paddingInline2+ : edgeCompStyles.paddingInline3+ : null;+const button = (<buttonref={ref}@@ -356,6 +384,8 @@ export const XDSButton = forwardRef<HTMLButtonElement, XDSButtonProps>(isIconOnly && styles.iconOnly,buttonDisabled && styles.disabled,isLoadingState && loadingStyles.loading,+ edgePaddingSignal,+ edgeCompStyle,)}{...props}onClick={handleClick}>diff --git a/packages/core/src/Layout/__tests__/edgeCompensation.test.tsx b/packages/core/src/Layout/__tests__/edgeCompensation.test.tsxnew file mode 100644index 0000000000..cbe74ea8ba--- /dev/null+++ b/packages/core/src/Layout/__tests__/edgeCompensation.test.tsx@@ -0,0 +1,189 @@+/**+ * @file edgeCompensation.test.tsx+ * @input Uses vitest, @testing-library/react+ * @output Unit tests for edge compensation pattern+ * @position Testing; validates edgeCompensation.stylex.ts, TopNav edge signals,+ * and Button ghost variant edge compensation behavior+ */++import {describe, it, expect} from 'vitest';+import {render, screen} from '@testing-library/react';+import {XDSTopNav} from '../../TopNav/XDSTopNav';+import {XDSButton} from '../../Button/XDSButton';+import {XDSBanner} from '../../Banner/XDSBanner';++describe('Edge Compensation', () => {+ describe('TopNav edge signals', () => {+ it('sets --container-padding-inline on the nav element', () => {+ render(+ <XDSTopNav+ label="Test nav"+ endContent={<span data-testid="end">End</span>}+ />,+ );+ const nav = screen.getByRole('navigation');+ expect(nav).toBeInTheDocument();+ // The nav should have the container-padding-inline style set+ // (StyleX applies this as a class — we verify the element renders correctly)+ expect(nav).toHaveAttribute('class');+ });++ it('renders endContent slot with edge-end signal wrapper', () => {+ render(+ <XDSTopNav+ label="Test nav"+ endContent={<span data-testid="end-item">Action</span>}+ />,+ );+ const endItem = screen.getByTestId('end-item');+ // The parent wrapper should have a class applied (edgeSignals.end)+ expect(endItem.parentElement).toHaveAttribute('class');+ });++ it('renders leftSection with edge-start signal wrapper', () => {+ render(+ <XDSTopNav+ label="Test nav"+ title={<span data-testid="title">Logo</span>}+ />,+ );+ const title = screen.getByTestId('title');+ // title > title wrapper > leftSection (with edgeSignals.start)+ const leftSection = title.parentElement?.parentElement;+ expect(leftSection).toHaveAttribute('class');+ });+ });++ describe('Banner edge signals', () => {+ it('sets --container-padding-inline on the banner header', () => {+ render(<XDSBanner status="info" title="Test" isDismissable />);+ // Banner renders with role="status" for info+ const banner = screen.getByRole('status');+ expect(banner).toBeInTheDocument();+ });++ it('renders dismiss button without a wrapper div', () => {+ render(<XDSBanner status="info" title="Test" isDismissable />);+ const dismissButton = screen.getByRole('button', {name: 'Dismiss'});+ expect(dismissButton).toBeInTheDocument();+ // The dismiss button should NOT be wrapped in an extra div with+ // manual negative margin — it should be a direct child of the endArea+ // The parent should be the endArea div (which has edgeSignals.end)+ const parent = dismissButton.closest('[class]')?.parentElement;+ expect(parent).not.toBeNull();+ });+ });++ describe('Button ghost variant edge compensation', () => {+ it('applies edge compensation class to ghost text button', () => {+ render(+ <XDSButton label="Action" variant="ghost" data-testid="ghost-btn" />,+ );+ const button = screen.getByRole('button', {name: 'Action'});+ // Ghost buttons should have additional style classes for edge compensation+ const classCount = (button.getAttribute('class') || '').split(' ').length;+ // Ghost button has: base + ghost variant + edge compensation = more classes+ // than a primary button+ expect(classCount).toBeGreaterThan(0);+ });++ it('applies edge compensation class to ghost icon-only button', () => {+ render(+ <XDSButton label="Settings" variant="ghost" icon={<span>gear</span>} />,+ );+ const button = screen.getByRole('button', {name: 'Settings'});+ expect(button).toBeInTheDocument();+ });++ it('does not apply edge compensation to primary variant', () => {+ const {container: primaryContainer} = render(+ <XDSButton label="Primary" variant="primary" />,+ );+ const {container: ghostContainer} = render(+ <XDSButton label="Ghost" variant="ghost" />,+ );+ const primaryClasses =+ primaryContainer.querySelector('button')?.getAttribute('class') || '';+ const ghostClasses =+ ghostContainer.querySelector('button')?.getAttribute('class') || '';+ // Ghost button should have more classes than primary (edge compensation adds classes)+ expect(ghostClasses.split(' ').length).toBeGreaterThan(+ primaryClasses.split(' ').length,+ );+ });++ it('does not apply edge compensation to secondary variant', () => {+ const {container: secondaryContainer} = render(+ <XDSButton label="Secondary" variant="secondary" />,+ );+ const {container: ghostContainer} = render(+ <XDSButton label="Ghost" variant="ghost" />,+ );+ const secondaryClasses =+ secondaryContainer.querySelector('button')?.getAttribute('class') || '';+ const ghostClasses =+ ghostContainer.querySelector('button')?.getAttribute('class') || '';+ // Ghost button should have more classes than secondary (edge compensation adds classes)+ expect(ghostClasses.split(' ').length).toBeGreaterThan(+ secondaryClasses.split(' ').length,+ );+ });+ });++ describe('TopNav + Button integration', () => {+ it('renders ghost button inside TopNav endContent', () => {+ render(+ <XDSTopNav+ label="App nav"+ endContent={+ <XDSButton+ label="Search"+ variant="ghost"+ icon={<span>search</span>}+ />+ }+ />,+ );+ const button = screen.getByRole('button', {name: 'Search'});+ expect(button).toBeInTheDocument();+ expect(screen.getByRole('navigation')).toContainElement(button);+ });++ it('renders primary button inside TopNav endContent without compensation', () => {+ render(+ <XDSTopNav+ label="App nav"+ endContent={<XDSButton label="Save" variant="primary" />}+ />,+ );+ const button = screen.getByRole('button', {name: 'Save'});+ expect(button).toBeInTheDocument();+ });++ it('renders multiple buttons in endContent', () => {+ render(+ <XDSTopNav+ label="App nav"+ endContent={+ <>+ <XDSButton+ label="Search"+ variant="ghost"+ icon={<span>search</span>}+ />+ <XDSButton+ label="Settings"+ variant="ghost"+ icon={<span>gear</span>}+ />+ </>+ }+ />,+ );+ expect(screen.getByRole('button', {name: 'Search'})).toBeInTheDocument();+ expect(+ screen.getByRole('button', {name: 'Settings'}),+ ).toBeInTheDocument();+ });+ });+});diff --git a/packages/core/src/Layout/container.stylex.ts b/packages/core/src/Layout/container.stylex.tsindex c66461a610..6669d8c846 100644--- a/packages/core/src/Layout/container.stylex.ts+++ b/packages/core/src/Layout/container.stylex.ts@@ -58,6 +58,30 @@ const containerPaddingStyles = stylex.create({spacing12: {'--container-padding': spacingVars['--spacing-12']},});+/**+ * Container inline padding styles for edge compensation.+ * Sets --container-padding-inline so edge-compensating children (ghost buttons, etc.)+ * know the inline padding to compensate against. Defaults to the same value as+ * --container-padding for isotropic containers; containers with asymmetric padding+ * (e.g., TopNav, Banner) set this directly.+ */+const containerPaddingInlineStyles = stylex.create({+ spacing0: {'--container-padding-inline': spacingVars['--spacing-0']},+ spacing0_5: {'--container-padding-inline': spacingVars['--spacing-0-5']},+ spacing1: {'--container-padding-inline': spacingVars['--spacing-1']},+ spacing2: {'--container-padding-inline': spacingVars['--spacing-2']},+ spacing3: {'--container-padding-inline': spacingVars['--spacing-3']},+ spacing4: {'--container-padding-inline': spacingVars['--spacing-4']},+ spacing5: {'--container-padding-inline': spacingVars['--spacing-5']},+ spacing6: {'--container-padding-inline': spacingVars['--spacing-6']},+ spacing7: {'--container-padding-inline': spacingVars['--spacing-7']},+ spacing8: {'--container-padding-inline': spacingVars['--spacing-8']},+ spacing9: {'--container-padding-inline': spacingVars['--spacing-9']},+ spacing10: {'--container-padding-inline': spacingVars['--spacing-10']},+ spacing11: {'--container-padding-inline': spacingVars['--spacing-11']},+ spacing12: {'--container-padding-inline': spacingVars['--spacing-12']},+});+const paddingOuterXStyles = stylex.create({spacing0: {'--layout-padding-outer-x': spacingVars['--spacing-0']},spacing0_5: {'--layout-padding-outer-x': spacingVars['--spacing-0-5']},@@ -169,6 +193,7 @@ export interface ContainerOptions {** Sets CSS variables for padding that child layout components read:* - `--container-padding` — Default padding for simple content+ * - `--container-padding-inline` — Inline padding for edge compensation* - `--layout-padding-outer-x`, `--layout-padding-outer-y`* - `--layout-padding-inner-x`, `--layout-padding-inner-y`*@@ -201,6 +226,10 @@ export function container({return [baseStyles.container,containerPaddingStyles[padding],+ // Set --container-padding-inline for edge compensation. When paddingOuterX+ // differs from the base padding, use paddingOuterX since that's the actual+ // inline padding at the container edges.+ containerPaddingInlineStyles[paddingOuterX],paddingOuterXStyles[paddingOuterX],paddingOuterYStyles[paddingOuterY],paddingInnerXStyles[paddingInnerX],diff --git a/packages/core/src/Layout/edgeCompensation.stylex.ts b/packages/core/src/Layout/edgeCompensation.stylex.tsnew file mode 100644index 0000000000..03e39eddd4--- /dev/null+++ b/packages/core/src/Layout/edgeCompensation.stylex.ts@@ -0,0 +1,136 @@+/**+ * @file edgeCompensation.stylex.ts+ * @input Uses @stylexjs/stylex+ * @output StyleX utilities for automatic edge padding compensation+ * @position Layout utility; used by containers (TopNav, LayoutHeader, Banner, etc.)+ * and components with transparent variants (Button ghost/tertiary)+ *+ * ## Edge Compensation Pattern+ *+ * Interactive components with transparent padding (ghost buttons, tertiary buttons)+ * create excess visual space at container edges. The container's padding + the+ * component's own transparent padding doubles up. Solid buttons don't have this+ * problem — their padding is visually filled.+ *+ * This module provides a two-layer solution:+ *+ * 1. **Containers** set spatial signals via CSS custom properties:+ * - `--edge-start: 1` / `--edge-end: 1` on edge-adjacent slots+ * - `--container-padding-inline` on the container root (the inline padding value)+ *+ * 2. **Components** with flat/transparent variants read these signals and+ * self-adjust their margins, clamped to `min(own-padding, container-padding-inline)`.+ *+ * The compensation formula:+ * ```+ * margin = var(--edge-*, 0) * -1 * min(own-padding, var(--container-padding-inline, 0px))+ * ```+ *+ * - When not at an edge: `--edge-*` is 0, so margin is 0 (no effect)+ * - When at an edge: margin pulls the component toward the edge by the smaller+ * of its own padding or the container's inline padding+ *+ * ### Why --container-padding-inline instead of --container-padding?+ *+ * Edge compensation is always an inline (horizontal) adjustment. Many containers+ * have different inline vs block padding (e.g., Banner: paddingInline=spacing-4,+ * paddingBlock=spacing-3; TopNav: paddingInline=spacing-4, no block padding).+ * Using the isotropic `--container-padding` would be semantically misleading and+ * could cause incorrect vertical compensation if a future component reads it for+ * block-direction adjustments. The existing `--container-padding` variable is used+ * by Divider and Section for edge-to-edge bleeds in both directions — we don't+ * want to overload it with a value that only represents one axis.+ *+ * SYNC: When modified, update /packages/core/src/Layout/README.md+ */++import * as stylex from '@stylexjs/stylex';++// =============================================================================+// Container-side: Edge signal styles+// =============================================================================++/**+ * Styles for containers to mark slots at their edges.+ *+ * Apply these to wrapper divs around slot content (startContent, endContent, etc.)+ * so child components know they're at a container boundary.+ *+ * The container must also set `--container-padding-inline` on its root element+ * so components know how much inline room is available for compensation.+ *+ * @example+ * ```tsx+ * // In TopNav:+ * <div {...stylex.props(edgeSignals.start)}>+ * {startContent}+ * </div>+ * <div {...stylex.props(edgeSignals.end)}>+ * {endContent}+ * </div>+ * ```+ */+export const edgeSignals = stylex.create({+ /** Mark slot as being at the inline-start edge of the container */+ start: {+ '--edge-start': '1',+ },+ /** Mark slot as being at the inline-end edge of the container */+ end: {+ '--edge-end': '1',+ },+ /** Mark slot as being at both edges (e.g., a single-slot container) */+ both: {+ '--edge-start': '1',+ '--edge-end': '1',+ },+});++// =============================================================================+// Component-side: Edge compensation styles+// =============================================================================++/**+ * Styles for components to self-adjust at container edges.+ *+ * Components with transparent/flat variants (ghost buttons, tertiary buttons,+ * icon-only buttons) should apply these styles to compensate for doubled padding+ * at container edges.+ *+ * The compensation is `min(own-padding, container-padding-inline)` — never more+ * than either value. When not at an edge (signals default to 0), no compensation+ * is applied.+ *+ * Components must set `--component-padding-inline` on themselves so the+ * compensation formula knows the component's own inline padding. This makes+ * edge compensation theme-safe — if a theme changes the button's internal+ * padding, the compensation adjusts automatically.+ *+ * @example+ * ```tsx+ * // In XDSButton, for ghost variant:+ * const styles = stylex.create({+ * ghost: {+ * paddingInline: spacingVars['--spacing-3'],+ * '--component-padding-inline': spacingVars['--spacing-3'],+ * },+ * });+ *+ * {...stylex.props(+ * styles.base,+ * styles.ghost,+ * edgeCompensation.self,+ * )}+ * ```+ */+export const edgeCompensation = stylex.create({+ /**+ * Self-compensating edge style. Reads --component-padding-inline from the+ * component itself. The component must set this variable to its own inline+ * padding value (typically via the same spacing token used for paddingInline).+ */+ self: {+ marginInlineStart: `calc(var(--edge-start, 0) * -1 * min(var(--component-padding-inline, 0px), var(--container-padding-inline, 0px)))`,+ marginInlineEnd: `calc(var(--edge-end, 0) * -1 * min(var(--component-padding-inline, 0px), var(--container-padding-inline, 0px)))`,+ },+});diff --git a/packages/core/src/Layout/index.ts b/packages/core/src/Layout/index.tsindex f5c791585a..1b08d6e65b 100644--- a/packages/core/src/Layout/index.ts+++ b/packages/core/src/Layout/index.ts@@ -11,6 +11,9 @@export {container} from './container.stylex';export type {ContainerOptions, SpacingToken} from './container.stylex';+// Edge compensation utility+export {edgeSignals, edgeCompensation} from './edgeCompensation.stylex';+// Stack utilities (re-exported from Stack module)export {stack} from '../Stack/stack.stylex';export type {diff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsxindex e7f6a8a90f..af5964054a 100644--- a/packages/core/src/TopNav/XDSTopNav.tsx+++ b/packages/core/src/TopNav/XDSTopNav.tsx@@ -21,6 +21,7 @@ import * as stylex from '@stylexjs/stylex';import {colorVars, spacingVars} from '../theme/tokens.stylex';import {ThemeContext} from '../theme/ThemeContext';import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';+import {edgeSignals} from '../Layout/edgeCompensation.stylex';/*** Base TopNav styles@@ -33,6 +34,10 @@ const styles = stylex.create({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+ // has no block padding (fixed height) — the isotropic variable would be misleading.+ '--container-padding-inline': spacingVars['--spacing-4'],},// Flex layout (default, used when no centerContent)baseFlex: {@@ -163,7 +168,7 @@ export const XDSTopNav = forwardRef<HTMLElement, XDSTopNavProps>(rootOverride,)}{...props}>- <div {...stylex.props(styles.leftSection)}>+ <div {...stylex.props(styles.leftSection, edgeSignals.start)}>{title && <div {...stylex.props(styles.title)}>{title}</div>}{startContent && (<div {...stylex.props(styles.startContent)}>{startContent}</div>@@ -173,10 +178,14 @@ export const XDSTopNav = forwardRef<HTMLElement, XDSTopNavProps>(<div {...stylex.props(styles.centerContent)}>{centerContent}</div>)}{hasCenterContent ? (- <div {...stylex.props(styles.rightSection)}>{endContent}</div>+ <div {...stylex.props(styles.rightSection, edgeSignals.end)}>+ {endContent}+ </div>) : (endContent && (- <div {...stylex.props(styles.endContent)}>{endContent}</div>+ <div {...stylex.props(styles.endContent, edgeSignals.end)}>+ {endContent}+ </div>))}</nav>