@astryxdesign/core 0.1.0 → 0.1.1-canary.129bf0e

package/src/EmptyState/EmptyState.test.tsx

@@ -45,11 +45,13 @@ describe('EmptyState', () => {
       />,
     );
     expect(screen.getByText('Try adjusting your search.')).toBeInTheDocument();
+    // Description renders as <div> (never <p>) so block content composes safely.
+    expect(screen.getByText('Try adjusting your search.').tagName).toBe('DIV');
   });
 
   it('does not render description when not provided', () => {
-    const {container} = render(<EmptyState title="No results" />);
-    expect(container.querySelector('p')).not.toBeInTheDocument();
+    render(<EmptyState title="No results" />);
+    expect(screen.queryByText('Try adjusting your search.')).toBeNull();
   });
 
   it('renders with icon', () => {

package/src/EmptyState/EmptyState.tsx

@@ -174,13 +174,17 @@ export function EmptyState({
           title,
         )}
         {description != null && (
-          <p
+          // Rendered as <div> (not <p>): description accepts ReactNode and a
+          // <p> cannot legally contain block children, which causes hydration
+          // mismatches. The StyleX style sets margin: 0, so appearance is
+          // unchanged.
+          <div
             {...stylex.props(
               styles.description,
               isCompact && styles.descriptionCompact,
             )}>
             {description}
-          </p>
+          </div>
         )}
       </div>
       {actions != null && (

package/src/FormLayout/FormLayout.doc.mjs

@@ -20,7 +20,7 @@ export const docs = {
       name: 'children',
       type: 'ReactNode',
       description:
-        'Form fields to arrange. Accepts XDS inputs (TextInput, Selector, etc.) and Field-wrapped custom controls.',
+        'Form fields to arrange. Accepts Astryx inputs (TextInput, Selector, etc.) and Field-wrapped custom controls.',
     },
     {
       name: 'xstyle',
@@ -68,7 +68,7 @@ export const docsZh = {
       name: 'children',
       type: 'ReactNode',
       description:
-        '要排列的表单字段。接受 XDS 输入组件（TextInput、Selector 等）和 Field 包装的自定义控件。',
+        '要排列的表单字段。接受 Astryx 输入组件（TextInput、Selector 等）和 Field 包装的自定义控件。',
     },
     {
       name: 'xstyle',
@@ -122,7 +122,7 @@ export const docsDense = {
   },
   propDescriptions: {
     direction: 'Field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right w/ equal flex-grow, horizontal-labels uses CSS Grid w/ labels left of inputs (collapses <=480px).',
-    children: 'Form fields to arrange. Accepts XDS inputs + Field-wrapped custom controls.',
+    children: 'Form fields to arrange. Accepts Astryx inputs + Field-wrapped custom controls.',
     xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
   },
 };

package/src/HoverCard/HoverCard.doc.mjs

@@ -108,6 +108,7 @@ export const docs = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
     ],
     anatomy: [
       {name: 'Trigger', required: true, description: 'The element that opens the hover card on hover or focus: a button, link, or inline text.'},
@@ -216,6 +217,7 @@ export const docsZh = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
     ],
   },
 };
@@ -233,6 +235,7 @@ export const docsDense = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a block-content HoverCard directly inside phrasing-only contexts (<p>, <label>, heading); it renders inline so block content is invalid HTML there. Wrap surrounding text in a block element instead.' },
     ],
   },
   components: [

package/src/HoverCard/HoverCard.test.tsx

@@ -10,7 +10,10 @@
  */
 
 import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
+import {renderToString} from 'react-dom/server';
+import {hydrateRoot} from 'react-dom/client';
+import {StrictMode} from 'react';
 import {HoverCard} from './HoverCard';
 
 // Store original matches to restore later
@@ -73,6 +76,31 @@ describe('HoverCard', () => {
     expect(paragraph?.querySelector('div')).toBeNull();
   });
 
+  it('renders the floating layer with inline-safe markup (no block elements in a paragraph)', () => {
+    // HoverCard renders its floating layer inline (no portal), so the layer
+    // must be phrasing content to stay valid — and stay put on hydration —
+    // inside a <p>. Assert the layer popover element is a <span> and that the
+    // paragraph contains no <div> descendants at all.
+    const {container} = render(
+      <p>
+        Before{' '}
+        <HoverCard content={<span>Card content</span>}>
+          <a href="#trigger">Trigger</a>
+        </HoverCard>{' '}
+        after
+      </p>,
+    );
+
+    const paragraph = container.querySelector('p');
+    const layer = screen.getByText('Card content').closest('[popover]');
+
+    expect(layer).not.toBeNull();
+    expect(layer?.tagName).toBe('SPAN');
+    // The whole layer subtree lives inside the paragraph with no block boxes.
+    expect(paragraph?.contains(layer as Node)).toBe(true);
+    expect(paragraph?.querySelector('div')).toBeNull();
+  });
+
   it('does not show content initially', () => {
     render(
       <HoverCard content={<span>Card content</span>}>
@@ -84,7 +112,7 @@ describe('HoverCard', () => {
     expect(content).toBeInTheDocument();
   });
 
-  it('applies the theme body font to the portaled layer', () => {
+  it('applies the theme body font to the floating layer', () => {
     render(
       <HoverCard content={<span>Card content</span>}>
         <button type="button">Trigger</button>
@@ -370,4 +398,152 @@ describe('HoverCard', () => {
       expect(onOpenChange).not.toHaveBeenCalledWith(true);
     });
   });
+
+  describe('SSR / hydration', () => {
+    // Regression coverage for the hydration mismatch (#3107). The floating
+    // layer used to be portaled into document.body behind a
+    // `typeof document !== 'undefined'` gate: the server rendered nothing while
+    // the first client render emitted the portal, so the two trees disagreed.
+    //
+    // The layer is now rendered inline as inline-safe phrasing markup (a
+    // `<span popover>`), identically on the server and the client, so there is
+    // nothing for hydration to mismatch.
+
+    it('renders the floating layer in server markup (no document gate)', () => {
+      const html = renderToString(
+        <HoverCard content={<span>Card content</span>}>
+          <button type="button">Trigger</button>
+        </HoverCard>,
+      );
+
+      // The popover element is present in the server output...
+      expect(html).toContain('popover="manual"');
+      expect(html).toContain('Card content');
+      // ...and it is a <span> (inline-safe), not a <div>.
+      expect(html).toMatch(/<span[^>]*popover="manual"/);
+    });
+
+    it('keeps the floating layer inline-safe in server markup inside a paragraph', () => {
+      const html = renderToString(
+        <p>
+          Before{' '}
+          <HoverCard content={<span>Card content</span>}>
+            <a href="#trigger">Trigger</a>
+          </HoverCard>{' '}
+          after
+        </p>,
+      );
+
+      // No <div> is emitted inside the paragraph — the layer and its wrappers
+      // are all phrasing content, so the server string is valid <p> markup that
+      // the browser parser will not reparent (which would itself desync
+      // hydration).
+      expect(html).not.toContain('<div');
+      expect(html).toMatch(/<span[^>]*popover="manual"/);
+    });
+
+    it('server markup matches the first client render (no hydration mismatch)', async () => {
+      const tree = (
+        <StrictMode>
+          <p>
+            Glossary:{' '}
+            <HoverCard content={<span>Definition</span>}>
+              <a href="#term">term</a>
+            </HoverCard>
+            .
+          </p>
+        </StrictMode>
+      );
+
+      const serverHTML = renderToString(tree);
+
+      const container = document.createElement('div');
+      container.innerHTML = serverHTML;
+      document.body.appendChild(container);
+
+      // Capture any hydration diagnostics. React reports hydration mismatches
+      // both through console.error and through onRecoverableError.
+      const consoleErrorSpy = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {});
+      const recoverableErrors: unknown[] = [];
+
+      let root: ReturnType<typeof hydrateRoot>;
+      await act(async () => {
+        root = hydrateRoot(container, tree, {
+          onRecoverableError: error => {
+            recoverableErrors.push(error);
+          },
+        });
+      });
+
+      const hydrationErrors = consoleErrorSpy.mock.calls.filter(call =>
+        String(call[0] ?? '')
+          .toLowerCase()
+          .includes('hydrat'),
+      );
+
+      expect(hydrationErrors).toEqual([]);
+      expect(recoverableErrors).toEqual([]);
+
+      await act(async () => {
+        root.unmount();
+      });
+      consoleErrorSpy.mockRestore();
+      container.remove();
+    });
+
+    it('hydrates a default-open hover card without a mismatch', async () => {
+      vi.mocked(HTMLElement.prototype.showPopover).mockClear();
+
+      const tree = (
+        <HoverCard content={<span>Default open</span>} isDefaultOpen>
+          <button type="button">Trigger</button>
+        </HoverCard>
+      );
+
+      const serverHTML = renderToString(tree);
+      // isDefaultOpen must not leak the open state into SSR markup — the open
+      // call happens in an effect after hydration, so the server output is the
+      // same closed markup the first client render produces.
+      expect(serverHTML).toContain('popover="manual"');
+
+      const container = document.createElement('div');
+      container.innerHTML = serverHTML;
+      document.body.appendChild(container);
+
+      const consoleErrorSpy = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {});
+      const recoverableErrors: unknown[] = [];
+
+      let root: ReturnType<typeof hydrateRoot>;
+      await act(async () => {
+        root = hydrateRoot(container, tree, {
+          onRecoverableError: error => {
+            recoverableErrors.push(error);
+          },
+        });
+      });
+
+      const hydrationErrors = consoleErrorSpy.mock.calls.filter(call =>
+        String(call[0] ?? '')
+          .toLowerCase()
+          .includes('hydrat'),
+      );
+      expect(hydrationErrors).toEqual([]);
+      expect(recoverableErrors).toEqual([]);
+
+      // The card opens after hydration via the mount effect.
+      await waitFor(() => {
+        expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+      });
+
+      await act(async () => {
+        root.unmount();
+      });
+      consoleErrorSpy.mockRestore();
+      container.remove();
+    });
+  });
 });

package/src/HoverCard/HoverCard.tsx

@@ -4,9 +4,9 @@
 
 /**
  * @file HoverCard.tsx
- * @input Uses React, ReactDOM createPortal, useHoverCard hook
+ * @input Uses React, useHoverCard hook
  * @output Exports HoverCard component for hover/focus triggered layers
- * @position Layer component; uses inline-safe trigger wrapper and portals floating layer
+ * @position Layer component; uses inline-safe trigger wrapper and renders the floating layer inline
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/HoverCard/HoverCard.test.tsx
@@ -15,13 +15,7 @@
  * - /packages/cli/templates/blocks/components/HoverCard/ (showcase blocks)
  */
 
-import React, {
-  useCallback,
-  useRef,
-  type ReactElement,
-  type ReactNode,
-} from 'react';
-import {createPortal} from 'react-dom';
+import {useCallback, useRef, type ReactElement, type ReactNode} from 'react';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import {useHoverCard, type HoverCardFocusTrigger} from './useHoverCard';
@@ -245,13 +239,23 @@ export function HoverCard({
     };
   }, [textOnly, hoverCard.ref, hoverCard.describedBy]);
 
-  const renderedHoverCard =
-    typeof document !== 'undefined'
-      ? createPortal(
-          hoverCard.renderHoverCard(content, {xstyle, className, style}),
-          document.body,
-        )
-      : null;
+  // Render the floating layer inline, in the same place on the server and the
+  // client. The layer is a `popover` element opened via the Popover API, so the
+  // browser promotes it to the top layer when shown — that already escapes
+  // ancestor clipping, stacking, and transform containing-block traps, and CSS
+  // anchor positioning resolves the trigger reference regardless of where the
+  // element sits in the DOM, so no portal is needed to "escape" layout.
+  //
+  // The layer renders as inline-safe phrasing markup (a `<span>`, see
+  // useHoverCard), which stays put inside a `<p>` instead of being reparented
+  // by the HTML parser. That keeps the server markup and the first client
+  // render identical, so there is no hydration mismatch — and it preserves the
+  // inline-safety guarantee (no block elements injected into a paragraph).
+  const renderedHoverCard = hoverCard.renderHoverCard(content, {
+    xstyle,
+    className,
+    style,
+  });
 
   // For text-only children: use inline span with ref on wrapper
   if (textOnly) {

package/src/HoverCard/useHoverCard.tsx

@@ -58,8 +58,12 @@ const styles = stylex.create({
     marginInlineStart: spacingVars['--spacing-1'],
     marginInlineEnd: spacingVars['--spacing-1'],
   },
-  // Content wrapper for padding and mouse events
+  // Content wrapper for padding and mouse events.
+  // `display: block` keeps the wrapper a block box even though it renders as a
+  // `span` (the layer uses inline-safe phrasing markup so it is valid inside a
+  // paragraph and produces identical server/client markup).
   content: {
+    display: 'block',
     paddingBlockStart: spacingVars['--spacing-3'],
     paddingBlockEnd: spacingVars['--spacing-3'],
     paddingInlineStart: spacingVars['--spacing-3'],
@@ -234,9 +238,7 @@ function isFocusable(element: HTMLElement): boolean {
  * {hoverCard.renderHoverCard(<ProfileCard user={user} />)}
  * ```
  */
-export function useHoverCard(
-  options: HoverCardOptions = {},
-): HoverCardReturn {
+export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
   const {
     placement = 'above',
     alignment = 'center',
@@ -454,14 +456,14 @@ export function useHoverCard(
         placement: renderPlacement,
         alignment: props?.alignment ?? alignment,
         xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
+        // Render the layer as inline-safe phrasing markup so HoverCard stays
+        // valid (and hydration-stable) inside inline contexts like a `<p>`.
+        as: 'span' as const,
       };
 
       return layer.render(
-        <div
-          {...mergeProps(
-            themeProps('hovercard'),
-            stylex.props(styles.content),
-          )}
+        <span
+          {...mergeProps(themeProps('hovercard'), stylex.props(styles.content))}
           onMouseEnter={() => {
             isHoveringContentRef.current = true;
             clearTimeouts();
@@ -502,7 +504,7 @@ export function useHoverCard(
             scheduleHide();
           }}>
           {children}
-        </div>,
+        </span>,
         renderProps,
       );
     },

package/src/Icon/Icon.doc.mjs

@@ -17,7 +17,7 @@ export const docs = {
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'error' | 'warning' | 'inherit'",
-      description: 'Color variant mapped to XDS icon color tokens.',
+      description: 'Color variant mapped to Astryx icon color tokens.',
       default: "'inherit'",
     },
     {
@@ -62,7 +62,7 @@ export const docsZh = {
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'error' | 'warning' | 'inherit'",
-      description: '映射到 XDS 图标颜色令牌的颜色变体。',
+      description: '映射到 Astryx 图标颜色令牌的颜色变体。',
       default: "'inherit'",
     },
     {
@@ -96,7 +96,7 @@ export const docsZh = {
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
   description:
-    'Renders icons w/ XDS design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
+    'Renders icons w/ Astryx design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
   usage: {
     description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
     bestPractices: [
@@ -113,7 +113,7 @@ export const docsDense = {
   },
   propDescriptions: {
     icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
-    color: 'Color variant mapped to XDS icon color tokens.',
+    color: 'Color variant mapped to Astryx icon color tokens.',
     size: 'Icon size.',
   },
 };

package/src/Item/Item.doc.mjs

@@ -51,7 +51,7 @@ export const docs = {
   ],
   usage: {
     description:
-      'A single, flexible item primitive that unifies the "start content + label + description + end content" pattern across XDS. Use it wherever you need a structured row: dropdown menus, selectors, contact lists, notifications, file browsers, and activity feeds.',
+      'A single, flexible item primitive that unifies the "start content + label + description + end content" pattern across Astryx. Use it wherever you need a structured row: dropdown menus, selectors, contact lists, notifications, file browsers, and activity feeds.',
     bestPractices: [
       {guidance: true, description: 'Use named slots (startContent, label, description, endContent) for the common layout. These cover the 80% case.'},
       {guidance: true, description: 'Use density="compact" for menus and dense lists, "balanced" for standard rows, and "spacious" for roomier layouts.'},
@@ -104,7 +104,7 @@ export const docsZh = {
   ],
   usage: {
     description:
-      '通用项目原语，统一 XDS 中 "起始内容 + 标签 + 描述 + 结束内容" 的布局模式。适用于下拉菜单、选择器、联系人列表、通知、文件浏览器和活动流等场景。',
+      '通用项目原语，统一 Astryx 中 "起始内容 + 标签 + 描述 + 结束内容" 的布局模式。适用于下拉菜单、选择器、联系人列表、通知、文件浏览器和活动流等场景。',
     bestPractices: [
       {guidance: true, description: '使用命名插槽（startContent、label、description、endContent）处理常见布局。'},
       {guidance: true, description: '菜单和密集列表使用 density="compact"，标准行使用 "balanced"，宽松布局使用 "spacious"。'},

package/src/Layer/useLayer.doc.mjs

@@ -78,7 +78,7 @@ export const docs = {
       name: 'render',
       type: '(children: ReactNode, props: ContextRenderProps | FixedRenderProps) => ReactNode',
       description:
-        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode.',
+        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree — the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal.',
     },
   ],
   usage: {
@@ -95,6 +95,11 @@ export const docs = {
         description:
           'Build on higher-level components like Popover, HoverCard, and Tooltip for common overlay patterns.',
       },
+      {
+        guidance: true,
+        description:
+          'Rely on the Popover API top layer to escape ancestor clipping and stacking — render the layer inline (no portal) so it inherits the trigger\u2019s theme cascade and keeps a natural focus order. Use `as: "span"` when the layer must be valid inside inline contexts like a paragraph.',
+      },
       {
         guidance: false,
         description:
@@ -125,7 +130,7 @@ export const docsDense = {
     hide: 'hide layer.',
     isOpen: 'whether layer is open.',
     id: 'unique ARIA id.',
-    render: 'renders popover element; pass placement/alignment or x/y.',
+    render: 'renders popover element; pass placement/alignment or x/y. Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal.',
   },
   usage: {
     description:

package/src/Layer/useLayer.tsx

@@ -79,6 +79,19 @@ export interface ContextRenderProps {
    * Merged after StyleX and anchor positioning styles.
    */
   style?: React.CSSProperties;
+  /**
+   * HTML tag to render the popover container as.
+   *
+   * Defaults to `'div'`. Pass `'span'` when the layer must render inline-safe
+   * markup — e.g. a `HoverCard` wrapping inline text inside a `<p>`. A `<span>`
+   * is phrasing content, so it stays put in the DOM tree instead of being
+   * reparented out of a paragraph by the HTML parser, which keeps server and
+   * client markup identical. The Popover API and CSS anchor positioning work
+   * the same on either tag.
+   *
+   * @default 'div'
+   */
+  as?: 'div' | 'span';
 }
 
 /**
@@ -369,6 +382,7 @@ export function useLayer(
         xstyle,
         className: extraClassName,
         style: extraStyle,
+        as: Container = 'div',
       } = props || {};
 
       // CSS anchor positioning (dynamic, not in StyleX)
@@ -383,15 +397,18 @@ export function useLayer(
         ? `${extraClassName} ${stylexResult.className ?? ''}`
         : stylexResult.className;
 
+      // Render as the requested tag. A `span` keeps the layer phrasing content
+      // so it is valid (and stays put on hydration) inside inline contexts like
+      // a `<p>`; `div` remains the default for block layers.
       return (
-        <div
+        <Container
           ref={popoverRefCallback}
           id={id}
           popover={lightDismiss ? 'auto' : 'manual'}
           className={combinedClassName}
           style={{...stylexResult.style, ...anchorStyle, ...extraStyle}}>
           {children}
-        </div>
+        </Container>
       );
     },
     [anchorId, id, lightDismiss, popoverRefCallback],

package/src/Layout/Layout.doc.mjs

@@ -29,7 +29,8 @@ export const docs = {
     {
       name: 'content',
       type: 'ReactNode',
-      description: 'Main content area (center).',
+      description:
+        'Main content area (center). Children passed to `<Layout>` render here too — `<Layout>{main}</Layout>` is shorthand for `<Layout content={main} />`.',
       slotElements: [
         {
           __element: 'LayoutContent',

package/src/Layout/Layout.tsx

@@ -157,6 +157,16 @@ export interface LayoutProps extends Omit<BaseProps, 'content'> {
    * Inline styles to apply to the root element.
    */
   style?: React.CSSProperties;
+
+  /**
+   * Children are a shorthand for the `content` slot:
+   * `<Layout>{main}</Layout>` is equivalent to `<Layout content={main} />`.
+   * The surrounding zones (`header`/`start`/`end`/`footer`) stay explicit
+   * props. If both `content` and `children` are provided, `content` wins.
+   * Accepting children keeps the natural `<Layout>…</Layout>` form from
+   * rendering a blank shell.
+   */
+  children?: ReactNode;
 }
 
 /**
@@ -222,6 +232,7 @@ function AreaProvider({
  * ```
  */
 export function Layout({
+  children,
   content,
   contentWidth,
   defaultHasDividers,
@@ -237,6 +248,9 @@ export function Layout({
   style,
 }: LayoutProps) {
   const isFill = height === 'fill';
+  // Children are a shorthand for the content slot; an explicit `content` prop
+  // wins when both are provided.
+  const resolvedContent = content ?? children;
 
   const dividerCtxValue = useMemo(
     () => (defaultHasDividers != null ? {defaultHasDividers} : null),
@@ -287,7 +301,7 @@ export function Layout({
             )}>
             <AreaProvider area="start">{start}</AreaProvider>
             <div {...stylex.props(...stackItem({size: 'fill'}))}>
-              <AreaProvider area="content">{content}</AreaProvider>
+              <AreaProvider area="content">{resolvedContent}</AreaProvider>
             </div>
             <AreaProvider area="end">{end}</AreaProvider>
           </div>

package/src/Layout/__tests__/childrenAsContent.test.tsx

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file childrenAsContent.test.tsx
+ * @input Uses vitest, @testing-library/react
+ * @output Verifies Layout renders children as a shorthand for the content slot
+ *   (so the natural `<Layout>…</Layout>` form never renders a blank shell), with
+ *   an explicit `content` prop taking precedence.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {Layout} from '../Layout';
+import {LayoutContent} from '../LayoutContent';
+
+describe('Layout children-as-content', () => {
+  it('renders nested children in the content slot', () => {
+    render(
+      <Layout>
+        <LayoutContent>
+          <span data-testid="body">Body</span>
+        </LayoutContent>
+      </Layout>,
+    );
+    expect(screen.getByTestId('body')).toBeInTheDocument();
+  });
+
+  it('renders bare children (no LayoutContent wrapper) too', () => {
+    render(
+      <Layout>
+        <span data-testid="bare">Bare</span>
+      </Layout>,
+    );
+    expect(screen.getByTestId('bare')).toBeInTheDocument();
+  });
+
+  it('lets an explicit content prop win over children', () => {
+    render(
+      <Layout content={<span data-testid="slot">Slot</span>}>
+        <span data-testid="child">Child</span>
+      </Layout>,
+    );
+    expect(screen.getByTestId('slot')).toBeInTheDocument();
+    expect(screen.queryByTestId('child')).not.toBeInTheDocument();
+  });
+
+  it('still supports the canonical slot-only API', () => {
+    render(
+      <Layout
+        content={
+          <LayoutContent>
+            <span data-testid="canon">Canonical</span>
+          </LayoutContent>
+        }
+      />,
+    );
+    expect(screen.getByTestId('canon')).toBeInTheDocument();
+  });
+});