@astryxdesign/core 0.2.0 → 0.3.0-canary.0b5a38e

package/src/Lightbox/Lightbox.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Lightbox/Lightbox.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Lightbox/index.ts (exports if types change)
  * - /apps/storybook/stories/Lightbox.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Lightbox/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Lightbox/ (showcase blocks)
  */
 
 import {
@@ -91,8 +91,8 @@ export interface LightboxProps extends BaseProps<HTMLDialogElement> {
    */
   onIndexChange?: (index: number) => void;
   /**
-   * Enable zoom on double-click (images only).
-   * When zoomed, drag to pan.
+   * Enable zoom on double-click, or Enter/Space/`+`/`-` via keyboard
+   * (images only). When zoomed, drag or use arrow keys to pan.
    * @default false
    */
   hasZoom?: boolean;
@@ -158,6 +158,16 @@ const styles = stylex.create({
       '@media (hover: hover)': 'zoom-in',
     },
   },
+  zoomTarget: {
+    outline: {
+      default: 'none',
+      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+    },
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': '2px',
+    },
+  },
   imageWrapperZoomed: {
     cursor: 'grab',
   },
@@ -205,7 +215,12 @@ const styles = stylex.create({
   navButton: {
     position: 'absolute',
     top: '50%',
-    transform: 'translateY(-50%)',
+    // The individual `translate` property, not `transform`: this style now
+    // lands on the Button root, and a `transform` here replaces the Button's
+    // own transform rules — measured: the `scale(0.98)` press feedback stops
+    // firing. `translate` composes with them, reproducing exactly what the
+    // removed wrapper element did (wrapper translated, button scaled).
+    translate: '0 -50%',
     zIndex: 1,
   },
   navPrev: {
@@ -234,12 +249,28 @@ const dynamicStyles = stylex.create({
   }),
 });
 
+/**
+ * Pan distance (px) per arrow-key press while zoomed. Offsets move the
+ * viewport in the arrow's direction — pressing ArrowRight reveals content to
+ * the right, so the image itself shifts left (negative x), matching how
+ * scrolling and pointer-drag panning feel.
+ */
+const KEYBOARD_PAN_STEP = 50;
+const KEYBOARD_PAN_OFFSETS: Record<string, [number, number]> = {
+  ArrowLeft: [KEYBOARD_PAN_STEP, 0],
+  ArrowRight: [-KEYBOARD_PAN_STEP, 0],
+  ArrowUp: [0, KEYBOARD_PAN_STEP],
+  ArrowDown: [0, -KEYBOARD_PAN_STEP],
+};
+
 /**
  * A fullscreen overlay for viewing images at full resolution.
  *
  * Supports single image and gallery modes. In gallery mode, provides
  * prev/next navigation via buttons and arrow keys. Optionally supports
- * zoom (double-click to toggle 2x) and pan (drag when zoomed).
+ * zoom (double-click, Enter/Space on the image, or `+`/`-` to toggle 2x)
+ * and pan (drag or arrow keys when zoomed; arrows navigate the gallery
+ * when not zoomed).
  *
  * Uses the native `<dialog>` element with `showModal()` for focus
  * trapping and top-layer placement. Dismiss via Escape, close button,
@@ -285,6 +316,7 @@ export function Lightbox({
 }: LightboxProps) {
   const t = useTranslator();
   const dialogRef = useRef<HTMLDialogElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
   const imageWrapperRef = useRef<HTMLDivElement>(null);
   const triggerElementRef = useRef<Element | null>(null);
 
@@ -390,10 +422,19 @@ export function Lightbox({
     [handleClose],
   );
 
-  // Backdrop click
+  // Backdrop click. The layout container fills the whole transparent dialog,
+  // so clicks on the visual backdrop (the dark area around the media) land on
+  // the container, never on the dialog element itself — treat both as the
+  // backdrop. A pan drag that ends over the backdrop still fires a click on
+  // the common ancestor; ignore it so releasing a drag doesn't dismiss.
+  const didDragRef = useRef(false);
   const handleBackdropClick = useCallback(
     (e: ReactMouseEvent<HTMLDialogElement>) => {
-      if (e.target === e.currentTarget) {
+      if (didDragRef.current) {
+        didDragRef.current = false;
+        return;
+      }
+      if (e.target === e.currentTarget || e.target === containerRef.current) {
         handleClose();
       }
     },
@@ -413,9 +454,52 @@ export function Lightbox({
     }
   }, [canNext, index, setIndex]);
 
-  // Keyboard navigation
+  // Zoom: double-click, Enter/Space on the image, or +/- keys toggle 1x ↔ 2x.
+  // Zoom changes are silent to assistive tech (only the transform changes), so
+  // mirror them in the polite live region, including a hint that arrow keys
+  // pan while zoomed.
+  const applyZoom = useCallback(
+    (next: number) => {
+      if (!hasZoom || isVideo || next === zoom) {
+        return;
+      }
+      setZoom(next);
+      setPan({x: 0, y: 0});
+      announce(
+        next > 1
+          ? t('@astryx.lightbox.zoomedIn')
+          : t('@astryx.lightbox.zoomedOut'),
+      );
+    },
+    [hasZoom, isVideo, zoom, announce, t],
+  );
+
+  const handleDoubleClick = useCallback(() => {
+    applyZoom(zoom === 1 ? 2 : 1);
+  }, [applyZoom, zoom]);
+
+  // Keyboard navigation. While zoomed, arrows pan the image (matching common
+  // lightbox conventions); when not zoomed they navigate the gallery.
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
+      if (hasZoom && !isVideo) {
+        if (e.key === '+' || e.key === '=') {
+          e.preventDefault();
+          applyZoom(2);
+          return;
+        }
+        if (e.key === '-') {
+          e.preventDefault();
+          applyZoom(1);
+          return;
+        }
+        if (zoom > 1 && KEYBOARD_PAN_OFFSETS[e.key] !== undefined) {
+          e.preventDefault();
+          const [dx, dy] = KEYBOARD_PAN_OFFSETS[e.key];
+          setPan(prev => ({x: prev.x + dx, y: prev.y + dy}));
+          return;
+        }
+      }
       if (e.key === 'ArrowLeft') {
         e.preventDefault();
         goToPrev();
@@ -424,22 +508,19 @@ export function Lightbox({
         goToNext();
       }
     },
-    [goToPrev, goToNext],
+    [hasZoom, isVideo, zoom, applyZoom, goToPrev, goToNext],
   );
 
-  // Zoom: double-click toggles 1x ↔ 2x
-  const handleDoubleClick = useCallback(() => {
-    if (!hasZoom) {
-      return;
-    }
-    if (zoom === 1) {
-      setZoom(2);
-      setPan({x: 0, y: 0});
-    } else {
-      setZoom(1);
-      setPan({x: 0, y: 0});
-    }
-  }, [hasZoom, zoom]);
+  // Enter/Space on the focused image wrapper (role="button") toggles zoom.
+  const handleImageKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLDivElement>) => {
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        handleDoubleClick();
+      }
+    },
+    [handleDoubleClick],
+  );
 
   // Pan: mouse drag when zoomed
   const handlePointerDown = useCallback(
@@ -448,6 +529,7 @@ export function Lightbox({
         return;
       }
       setIsDragging(true);
+      didDragRef.current = false;
       dragStartRef.current = {
         x: e.clientX,
         y: e.clientY,
@@ -464,6 +546,7 @@ export function Lightbox({
     }
 
     const handlePointerMove = (e: PointerEvent) => {
+      didDragRef.current = true;
       const dx = e.clientX - dragStartRef.current.x;
       const dy = e.clientY - dragStartRef.current.y;
       setPan({
@@ -485,6 +568,7 @@ export function Lightbox({
   }, [isDragging]);
 
   const isZoomed = zoom > 1;
+  const isZoomTarget = hasZoom && !isVideo;
   const imageTransform =
     zoom === 1
       ? null
@@ -514,49 +598,56 @@ export function Lightbox({
         style,
       )}
       {...props}>
-      <div {...stylex.props(styles.container)}>
+      <div ref={containerRef} {...stylex.props(styles.container)}>
         {/* Close button */}
-        <div {...stylex.props(styles.closeButton)}>
-          <IconButton
-            icon={<Icon icon="close" size="sm" color="inherit" />}
-            label={t('@astryx.lightbox.close')}
-            variant="ghost"
-            onClick={handleClose}
-            xstyle={styles.controlButton}
-          />
-        </div>
+        <IconButton
+          icon={<Icon icon="close" size="sm" color="inherit" />}
+          label={t('@astryx.lightbox.close')}
+          variant="ghost"
+          onClick={handleClose}
+          xstyle={[styles.closeButton, styles.controlButton]}
+        />
 
         {/* Gallery nav: prev — stays mounted and is disabled at the start of
             the range so pressing/arrowing to the boundary doesn't unmount the
             focused control and drop focus to <body>. */}
         {isGallery && (
-          <div {...stylex.props(styles.navButton, styles.navPrev)}>
-            <IconButton
-              icon={
-                <span {...stylex.props(rtlStyles.mirror)}>
-                  <Icon icon="chevronLeft" size="sm" color="inherit" />
-                </span>
-              }
-              label={t('@astryx.lightbox.previous')}
-              variant="ghost"
-              isDisabled={!canPrev}
-              onClick={goToPrev}
-              xstyle={styles.controlButton}
-            />
-          </div>
+          <IconButton
+            icon={
+              <Icon
+                icon="chevronLeft"
+                size="sm"
+                color="inherit"
+                xstyle={rtlStyles.mirror}
+              />
+            }
+            label={t('@astryx.lightbox.previous')}
+            variant="ghost"
+            isDisabled={!canPrev}
+            onClick={goToPrev}
+            xstyle={[styles.navButton, styles.navPrev, styles.controlButton]}
+          />
         )}
 
         {/* Media + caption group (centered together) */}
         <div {...stylex.props(styles.mediaGroup)}>
           <div
             ref={imageWrapperRef}
+            // The wrapper is a keyboard-operable zoom toggle when zoom is
+            // enabled: Enter/Space toggles, aria-pressed reflects state.
+            role={isZoomTarget ? 'button' : undefined}
+            tabIndex={isZoomTarget ? 0 : undefined}
+            aria-pressed={isZoomTarget ? isZoomed : undefined}
+            aria-label={isZoomTarget ? t('@astryx.lightbox.zoom') : undefined}
             {...stylex.props(
               styles.imageWrapper,
+              isZoomTarget && styles.zoomTarget,
               !isVideo && hasZoom && !isZoomed && styles.imageWrapperZoomable,
               !isVideo && isZoomed && styles.imageWrapperZoomed,
               !isVideo && isDragging && styles.imageWrapperDragging,
             )}
             onDoubleClick={isVideo ? undefined : handleDoubleClick}
+            onKeyDown={isZoomTarget ? handleImageKeyDown : undefined}
             onPointerDown={isVideo ? undefined : handlePointerDown}>
             {isVideo ? (
               <video
@@ -589,20 +680,21 @@ export function Lightbox({
         {/* Gallery nav: next — see "prev" above; stays mounted and disabled at
             the end of the range instead of unmounting. */}
         {isGallery && (
-          <div {...stylex.props(styles.navButton, styles.navNext)}>
-            <IconButton
-              icon={
-                <span {...stylex.props(rtlStyles.mirror)}>
-                  <Icon icon="chevronRight" size="sm" color="inherit" />
-                </span>
-              }
-              label={t('@astryx.lightbox.next')}
-              variant="ghost"
-              isDisabled={!canNext}
-              onClick={goToNext}
-              xstyle={styles.controlButton}
-            />
-          </div>
+          <IconButton
+            icon={
+              <Icon
+                icon="chevronRight"
+                size="sm"
+                color="inherit"
+                xstyle={rtlStyles.mirror}
+              />
+            }
+            label={t('@astryx.lightbox.next')}
+            variant="ghost"
+            isDisabled={!canNext}
+            onClick={goToNext}
+            xstyle={[styles.navButton, styles.navNext, styles.controlButton]}
+          />
         )}
 
         {/* Gallery counter */}

package/src/Link/Link.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Link',
@@ -143,7 +143,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Link',
   displayName: 'Link',
@@ -275,7 +275,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Styled anchor links w/ multiple variants + polymorphic link infra for custom link components (Next.js Link, React Router Link, etc.).',

package/src/Link/Link.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Link/Link.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Link/index.ts (exports if types change)
  * - /apps/storybook/stories/Link.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Link/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Link/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';

package/src/Link/LinkProvider.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'LinkProvider',
@@ -18,7 +18,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all Astryx components.',
   usage: {

package/src/Link/LinkProvider.tsx

@@ -22,8 +22,8 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Link/index.ts
  * - /packages/core/src/Link/Link.doc.mjs
- * - /packages/cli/templates/blocks/components/Link/ (showcase blocks)
- * - /packages/cli/templates/blocks/components/LinkProvider/ (example blocks)
+ * - /packages/cli/assets/templates/blocks/components/Link/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/LinkProvider/ (example blocks)
  */
 
 import {useMemo, type ReactNode} from 'react';

package/src/List/List.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'List',
@@ -95,7 +95,7 @@ export const docs = {
     ],
   },
 };
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -116,7 +116,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Vertical list for rendering item collections w/ consistent spacing, dividers, marker styles. Composition model: List wraps ListItem sub-components.',

package/src/List/List.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/List/List.test.tsx
  * - /packages/core/src/List/index.ts
  * - /apps/storybook/stories/List.stories.tsx
- * - /packages/cli/templates/blocks/components/List/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/List/ (showcase blocks)
  */
 
 import {useId, useMemo, type ReactNode} from 'react';

package/src/List/ListItem.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ListItem',
@@ -59,6 +59,11 @@ export const docs = {
       type: '(e: MouseEvent) => void',
       description: 'Click handler; enables the invisible button pattern.',
     },
+    {
+      name: 'interactiveRef',
+      type: 'RefObject<HTMLElement | null>',
+      description: 'Ref to a nested control (e.g. a checkbox in startContent) that owns the item\'s keyboard access and action. The row becomes an enlarged click/tap target that delegates surface clicks to it (useClickableContainer) and renders no invisible button/anchor, so the row adds no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href; those are ignored when set.',
+    },
     {
       name: 'href',
       type: 'string',
@@ -121,6 +126,11 @@ export const docsZh = {
       type: '(e: MouseEvent) => void',
       description: '点击处理函数；启用隐形按钮模式。',
     },
+    {
+      name: 'interactiveRef',
+      type: 'RefObject<HTMLElement | null>',
+      description: '指向嵌套控件（如 startContent 中的复选框）的 ref，该控件承载项目的键盘访问和操作。行成为更大的点击/触摸目标，将表面点击委托给该控件（useClickableContainer），且不渲染不可见按钮/锚点，因此行不会增加第二个 Tab 停留点（WCAG 4.1.2）。与 onClick/href 互斥——设置后二者将被忽略。',
+    },
     {
       name: 'href',
       type: 'string',
@@ -162,6 +172,8 @@ export const docsDense = {
     startContent: 'Content before label area (e.g. icon, avatar).',
     endContent: 'Content after label area (e.g. badge, chevron).',
     onClick: 'Click handler; enables invisible button pattern.',
+    interactiveRef:
+      'Ref to a nested control that owns the item\'s keyboard access/action; row delegates surface clicks to it (useClickableContainer), no invisible button/anchor, no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href.',
     href: 'Link URL; enables invisible anchor pattern.',
     target: 'Link target attribute, only when href provided. target="_blank" auto-adds noopener noreferrer.',
     rel: 'Link relationship tokens. noopener noreferrer are merged for target="_blank".',

package/src/List/ListItem.tsx

@@ -16,7 +16,7 @@
  * - /packages/core/src/List/List.test.tsx
  * - /packages/core/src/List/index.ts
  * - /apps/storybook/stories/List.stories.tsx
- * - /packages/cli/templates/blocks/components/List/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/List/ (showcase blocks)
  */
 
 import {use, type ReactNode} from 'react';
@@ -75,6 +75,17 @@ export interface ListItemProps extends BaseProps<HTMLLIElement> {
    */
   onClick?: (e: React.MouseEvent) => void;
 
+  /**
+   * Ref to a nested control inside the item (e.g. a checkbox in
+   * `startContent`) that already provides the item's keyboard access and
+   * action. When set, the item becomes an enlarged click/tap target that
+   * delegates surface clicks to that control via the `useClickableContainer`
+   * pattern: it renders no invisible button/anchor, so the row adds no second
+   * tab stop (WCAG 4.1.2 — one focusable control per option). Mutually
+   * exclusive with `onClick`/`href` — when set those are ignored.
+   */
+  interactiveRef?: React.RefObject<HTMLElement | null>;
+
   /**
    * URL for link items. Renders an invisible anchor element.
    * Automatically enables hover/press styles when provided.
@@ -199,6 +210,7 @@ export function ListItem({
   startContent,
   endContent,
   onClick,
+  interactiveRef,
   href,
   target,
   rel,
@@ -239,6 +251,7 @@ export function ListItem({
       description={description}
       endContent={endContent}
       onClick={onClick}
+      interactiveRef={interactiveRef}
       href={href}
       target={target as '_blank' | '_self'}
       rel={rel}

package/src/Markdown/Markdown.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Markdown',
@@ -128,6 +128,38 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-markdown', visualProps: ['density']},
+      {
+        className: 'astryx-markdown-heading',
+        visualProps: ['density', 'level'],
+      },
+      {
+        className: 'astryx-markdown-paragraph',
+        visualProps: ['density'],
+      },
+      {
+        className: 'astryx-markdown-list',
+        visualProps: ['density'],
+      },
+      {
+        className: 'astryx-markdown-codeblock',
+        visualProps: ['density'],
+      },
+      {
+        className: 'astryx-markdown-blockquote',
+        visualProps: ['density'],
+      },
+      {
+        className: 'astryx-markdown-table',
+        visualProps: ['density'],
+      },
+      {
+        className: 'astryx-markdown-hr',
+        visualProps: ['density'],
+      },
+      {
+        className: 'astryx-markdown-image',
+        visualProps: ['density'],
+      },
     ],
   },
   usage: {
@@ -292,6 +324,54 @@ export const docsZh = {
   theming: {
     targets: [
       {className: 'astryx-markdown', visualProps: ['density']},
+      {
+        className: 'astryx-markdown-heading',
+        visualProps: ['density', 'level'],
+        description:
+          '每个渲染的标题块（h1–h6）。覆盖 marginBlockStart/marginBlockEnd 可调整标题周围的间距；反映 data-density 和 data-level，因此主题可按密度和标题层级设置间距。仅适用于默认标题渲染——自定义的 components.heading 拥有自己的样式。',
+      },
+      {
+        className: 'astryx-markdown-paragraph',
+        visualProps: ['density'],
+        description:
+          '每个渲染的段落块。覆盖 marginBlockStart/marginBlockEnd 可调整段落之间的间距。反映 data-density，因此主题可以为不同密度设置不同的间距。',
+      },
+      {
+        className: 'astryx-markdown-list',
+        visualProps: ['density'],
+        description:
+          '每个渲染的列表块（有序、无序和任务列表）。覆盖 marginBlockStart/marginBlockEnd 可调整列表周围的间距；反映 data-density。',
+      },
+      {
+        className: 'astryx-markdown-codeblock',
+        visualProps: ['density'],
+        description:
+          '每个渲染的代码块外层容器。覆盖 marginBlockStart/marginBlockEnd 可调整代码块周围的间距；反映 data-density。仅适用于默认渲染——自定义的 components.code 拥有自己的样式。',
+      },
+      {
+        className: 'astryx-markdown-blockquote',
+        visualProps: ['density'],
+        description:
+          '每个渲染的引用块（与 astryx-blockquote 目标共用同一元素）。覆盖 marginBlockStart/marginBlockEnd 可调整引用块周围的间距；反映 data-density。仅适用于默认渲染——自定义的 components.blockquote 拥有自己的样式。',
+      },
+      {
+        className: 'astryx-markdown-table',
+        visualProps: ['density'],
+        description:
+          '每个渲染的表格外层容器。覆盖 marginBlockStart/marginBlockEnd 可调整表格周围的间距；反映 data-density。',
+      },
+      {
+        className: 'astryx-markdown-hr',
+        visualProps: ['density'],
+        description:
+          '每个渲染的水平分隔线。覆盖 marginBlockStart/marginBlockEnd 可调整分隔线周围的间距；反映 data-density。仅适用于默认渲染——自定义的 components.hr 拥有自己的样式。',
+      },
+      {
+        className: 'astryx-markdown-image',
+        visualProps: ['density'],
+        description:
+          '每个渲染的块级图片外层容器（以及损坏图片的占位符）。覆盖 marginBlockStart/marginBlockEnd 可调整图片周围的间距；反映 data-density。仅适用于默认渲染——自定义的 components.image 拥有自己的样式。',
+      },
     ],
   },
   usage: {