Skip to content

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.png
new file mode 100644
index 0000000000..27943d6d08
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-All-Features-Combined.png differ
diff --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-.png
new file mode 100644
index 0000000000..1e0d12d681
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-Collapsible-Content-Collapsed-.png differ
diff --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-.png
new file mode 100644
index 0000000000..fdc45d7805
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-Collapsible-Content-Expanded-.png differ
diff --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.png
new file mode 100644
index 0000000000..157feb4dd6
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Core-XDSBanner-Dismissable-With-Callback.png differ
diff --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.png
new file mode 100644
index 0000000000..036dd6dda1
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Core-XDSButton-Icon-And-End-Slot.png differ
diff --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.png
new file mode 100644
index 0000000000..290eb64089
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Core-XDSButton-With-End-Slot.png differ
diff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSHStack-Wrapping.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSHStack-Wrapping.png
new file mode 100644
index 0000000000..74fc95c0b2
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSHStack-Wrapping.png differ
diff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Default.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Default.png
new file mode 100644
index 0000000000..14ca572bdb
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Default.png differ
diff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Header-Layout.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Header-Layout.png
new file mode 100644
index 0000000000..2d604cbf83
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Header-Layout.png differ
diff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Horizontal-Alignments.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Horizontal-Alignments.png
new file mode 100644
index 0000000000..3cf64e2343
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Horizontal-Alignments.png differ
diff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Horizontal.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Horizontal.png
new file mode 100644
index 0000000000..74706c40a0
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Horizontal.png differ
diff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Page-Layout.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Page-Layout.png
new file mode 100644
index 0000000000..33da1447af
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Page-Layout.png differ
diff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Sidebar-Layout.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Sidebar-Layout.png
new file mode 100644
index 0000000000..b4d87c8dee
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Sidebar-Layout.png differ
diff --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.png
new file mode 100644
index 0000000000..7a4f371a2d
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Stack-Item-Cross-Align-Self.png differ
diff --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.png
new file mode 100644
index 0000000000..7ed3e9a0cc
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Stack-Item-Equal-Fill.png differ
diff --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.png
new file mode 100644
index 0000000000..1f282adeaa
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Stack-Item-Fill-Size.png differ
diff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Vertical-Alignments.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Vertical-Alignments.png
new file mode 100644
index 0000000000..1b6d12aecc
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Vertical-Alignments.png differ
diff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Vertical.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Vertical.png
new file mode 100644
index 0000000000..8df569c922
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Vertical.png differ
diff --git a/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Wrapping.png b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Wrapping.png
new file mode 100644
index 0000000000..74fc95c0b2
Binary files /dev/null and b/e2e/visual-regression.spec.ts-snapshots/Layout-XDSStack-Wrapping.png differ
diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsx
index 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 vertically
headerCentered: {
@@ -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 header
contentArea: {
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.tsx
index 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 = (
<button
ref={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.tsx
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.tsx
index 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>