@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/FileInput/FileInput.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file FileInput.tsx
- * @input Uses React, useId, Field, Icon, Spinner
+ * @input Uses React, useId, Field, Icon, Spinner, VisuallyHidden
  * @output Exports FileInput component, FileInputProps, FileInputStatus
  * @position Core implementation; consumed by index.ts, tested by FileInput.test.tsx
  *
@@ -13,7 +13,7 @@
  * - /packages/core/src/FileInput/FileInput.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/FileInput/index.ts (exports if types change)
  * - /apps/storybook/stories/FileInput.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/FileInput/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/FileInput/ (showcase blocks)
  */
 
 import {
@@ -40,11 +40,14 @@ import {
   Field,
   InputClearButton,
   type InputStatus,
-  type InputStatusType,
+  type FieldStatusVariant,
 } from '../Field';
-import {Icon, type IconName} from '../Icon';
+import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
+import {VisuallyHidden} from '../VisuallyHidden';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useClickableContainer} from '../hooks/useClickableContainer';
 import {useTooltip} from '../Tooltip';
 
 export type {
@@ -246,17 +249,6 @@ const styles = stylex.create({
     flex: 1,
     minWidth: 0,
   },
-  liveRegion: {
-    position: 'absolute',
-    width: 1,
-    height: 1,
-    padding: 0,
-    margin: -1,
-    overflow: 'hidden',
-    clip: 'rect(0, 0, 0, 0)',
-    whiteSpace: 'nowrap',
-    borderWidth: 0,
-  },
 });
 
 const statusBorderStyles = stylex.create({
@@ -358,6 +350,14 @@ export interface FileInputProps extends Omit<
    * Validation status for the input.
    */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * Description text displayed below the label.
    */
@@ -414,6 +414,7 @@ export function FileInput({
   isRequired = false,
   isLoading = false,
   status: statusProp,
+  statusVariant = 'attached',
   description,
   placeholder,
   mode = 'input',
@@ -430,22 +431,24 @@ export function FileInput({
   const id = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
-  const liveRegionID = useId();
+  const requiredID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
+  const containerRef = useRef<HTMLDivElement | null>(null);
   const [isDragOver, setIsDragOver] = useState(false);
   const [validationError, setValidationError] = useState<string | null>(null);
   const [, startTransition] = useTransition();
 
   // Announce successful file selection to screen readers via a persistent
-  // live region (forms-17). The component's own role="status" region only
-  // carries validation errors, so a successful attach was previously silent.
+  // live region (forms-17). Validation errors are announced (assertively) by
+  // the FieldStatus that the derived error status mounts, so only the
+  // successful attach needs an explicit announcement here.
   const announce = useAnnounce();
 
   // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the role="button" trigger (which already
-  // exists) and the trigger stays perceivable via aria-disabled instead of the
-  // native disabled attribute. Opening the picker is blocked by the isDisabled
-  // guards in handleClick / handleKeyDown / handleFiles.
+  // tooltip listeners attach to the visible container (which stays hoverable)
+  // and the trigger stays perceivable via aria-disabled instead of the native
+  // disabled attribute. Opening the picker is blocked by the isDisabled guards
+  // in the handlers.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -459,25 +462,27 @@ export function FileInput({
       ? {type: 'error' as const, message: validationError}
       : undefined);
 
-  const statusIconMap: Record<InputStatusType, IconName> = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
+  const {statusIcon, describedBy: statusTooltipDescribedBy} =
+    useInputStatusIcon({
+      status,
+      statusVariant,
+    });
 
-  const statusIconColorMap: Record<
-    InputStatusType,
-    'warning' | 'error' | 'success'
-  > = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
+  // Required state. The trigger is a real button, but AT does not reliably
+  // announce aria-required, so the trigger instead points its aria-describedby
+  // at a visually hidden "Required" span — mirroring the Field label's visible
+  // indicator (where isOptional takes precedence) and the pattern Slider uses
+  // for its thumbs.
+  const conveysRequired = isRequired && !isOptional;
 
   const ariaDescribedBy =
     [
       description ? descriptionID : null,
-      status?.message ? statusMessageID : null,
+      statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
+      // The tooltip variant renders no message box; describe the input by the
+      // tooltip's content instead so the status is still announced.
+      statusTooltipDescribedBy,
+      conveysRequired ? requiredID : null,
       showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
@@ -515,8 +520,9 @@ export function FileInput({
       onChange(result);
 
       // Announce the successful selection politely. Validation errors are
-      // handled by the role="status" region below, so only announce the
-      // attach here (do not double-announce errors).
+      // announced assertively by the FieldStatus that the derived error
+      // status mounts, so only announce the attach here (do not
+      // double-announce errors).
       if (errors.length === 0) {
         announce(
           valid.length === 1
@@ -574,6 +580,9 @@ export function FileInput({
     }
   }, [isDisabled]);
 
+  // Explicit keyboard activation so Enter/Space open the picker even where a
+  // synthetic keydown does not raise a native click. The isDisabled guard
+  // blocks activation while focusable-disabled.
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
       if ((e.key === 'Enter' || e.key === ' ') && !isDisabled) {
@@ -584,6 +593,16 @@ export function FileInput({
     [isDisabled],
   );
 
+  // Make the surface clickable without giving it an interactive role. Clicks on
+  // the nested clear/status controls are ignored by the hook, so those buttons
+  // are plain siblings — no nested-interactive violation.
+  const {onClick: onContainerClick, onMouseUp: onContainerMouseUp} =
+    useClickableContainer({
+      containerRef,
+      onClick: handleClick,
+      disabled: isDisabled,
+    });
+
   const handleDragEnter = useCallback(
     (e: DragEvent) => {
       e.preventDefault();
@@ -687,13 +706,7 @@ export function FileInput({
           )}>
           {fileNames ?? displayPlaceholder}
         </span>
-        {status && (
-          <Icon
-            icon={statusIconMap[status.type]}
-            size="md"
-            color={statusIconColorMap[status.type]}
-          />
-        )}
+        {statusIcon}
       </>
     );
   };
@@ -728,39 +741,21 @@ export function FileInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       <div
         ref={el => {
-          // Anchor + hover/focus listeners for the disabled-message tooltip.
-          // Handlers are gated internally by isEnabled, and anchor names
-          // compose, so attaching unconditionally is safe.
+          containerRef.current = el;
+          // Anchor + hover/focus listeners for the disabled-message tooltip on
+          // the visible container (the focusable trigger is visually hidden, so
+          // anchoring there would place the tooltip at a 1px box). focusin
+          // bubbles from the trigger button, so the tooltip still opens on
+          // keyboard focus. Handlers are gated internally by isEnabled.
           disabledMessageTooltip.ref(el);
         }}
-        role="button"
-        // With a disabledMessage the trigger keeps focusability via
-        // aria-disabled so the reason is focus-discoverable; opening the picker
-        // is still blocked by the isDisabled guards in the handlers.
-        tabIndex={isDisabled && !showsDisabledMessage ? -1 : 0}
-        aria-disabled={showsDisabledMessage ? 'true' : undefined}
-        onClick={handleClick}
-        onKeyDown={handleKeyDown}
-        // aria-label suppresses child content from the accessible name, so
-        // compose the selected filenames into it — otherwise a screen-reader
-        // user refocusing the control hears only the field label and cannot
-        // tell what (if anything) is attached.
-        aria-label={
-          hasFiles && fileNames
-            ? t('@astryx.fileInput.triggerWithFiles', {label, fileNames})
-            : label
-        }
-        aria-busy={isLoading || undefined}
-        // These describe the operable control, so they belong on the focusable
-        // role="button" wrapper — not the hidden tabIndex={-1} file input the
-        // user never focuses (forms-6).
-        aria-describedby={ariaDescribedBy}
-        aria-required={isRequired ? 'true' : undefined}
-        aria-invalid={status?.type === 'error' ? 'true' : undefined}
+        onClick={!isDisabled ? onContainerClick : undefined}
+        onMouseUp={!isDisabled ? onContainerMouseUp : undefined}
         {...dragDropProps}
         {...mergeProps(
           themeProps('file-input', {mode, status: status?.type ?? null}),
@@ -776,6 +771,40 @@ export function FileInput({
           className,
           style,
         )}>
+        {/* Visually hidden real button carrying the accessible role, name, and
+            ARIA. Kept as a sibling of the clear/status controls inside a
+            non-interactive container, so no interactive element nests inside
+            another (WCAG 4.1.2). The visible focus feedback is the container's
+            :focus-within border; the surface click is handled by the container
+            (VisuallyHidden disables the button's own pointer events), and
+            keyboard activation still fires here. */}
+        <VisuallyHidden>
+          <button
+            type="button"
+            // With a disabledMessage the trigger keeps focusability via
+            // aria-disabled so the reason is focus-discoverable; opening the
+            // picker is still blocked by the isDisabled guards in the handlers.
+            // Otherwise the native disabled attribute removes it from the tab
+            // order.
+            disabled={isDisabled && !showsDisabledMessage}
+            tabIndex={isDisabled && !showsDisabledMessage ? -1 : 0}
+            aria-disabled={showsDisabledMessage ? 'true' : undefined}
+            onClick={handleClick}
+            onKeyDown={handleKeyDown}
+            // aria-label suppresses child content from the accessible name, so
+            // compose the selected filenames into it — otherwise a
+            // screen-reader user refocusing the control hears only the field
+            // label and cannot tell what (if anything) is attached.
+            aria-label={
+              hasFiles && fileNames
+                ? t('@astryx.fileInput.triggerWithFiles', {label, fileNames})
+                : label
+            }
+            aria-busy={isLoading || undefined}
+            aria-describedby={ariaDescribedBy}
+            aria-invalid={status?.type === 'error' ? 'true' : undefined}
+          />
+        </VisuallyHidden>
         <input
           {...rest}
           ref={mergeRefs(ref, inputRef)}
@@ -786,7 +815,7 @@ export function FileInput({
           disabled={isDisabled}
           onChange={handleInputChange}
           // The visually-hidden native input is never focused (tabIndex={-1});
-          // its describedby/required/invalid live on the role="button" wrapper.
+          // its describedby/required/invalid live on the trigger button.
           aria-hidden="true"
           tabIndex={-1}
           {...stylex.props(styles.hiddenInput)}
@@ -799,13 +828,11 @@ export function FileInput({
           />
         )}
       </div>
-      <div
-        id={liveRegionID}
-        role="status"
-        aria-live="polite"
-        {...stylex.props(styles.liveRegion)}>
-        {validationError}
-      </div>
+      {conveysRequired && (
+        <VisuallyHidden id={requiredID}>
+          {t('@astryx.fileInput.required')}
+        </VisuallyHidden>
+      )}
       {showsDisabledMessage &&
         disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>

package/src/FormLayout/FormLayout.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: 'FormLayout',
@@ -52,7 +52,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'FormLayout',
   displayName: 'Form Layout',
@@ -100,7 +100,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Layout container for form fields w/ consistent spacing + direction.',

package/src/FormLayout/FormLayout.tsx

@@ -12,17 +12,14 @@
  * - /packages/core/src/FormLayout/FormLayout.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/FormLayout/index.ts (exports if types change)
  * - /apps/storybook/stories/FormLayout.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/FormLayout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/FormLayout/ (showcase blocks)
  */
 
 import {useMemo, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
-import {
-  FormLayoutContext,
-  type FormLayoutDirection,
-} from './FormLayoutContext';
+import {FormLayoutContext, type FormLayoutDirection} from './FormLayoutContext';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 

package/src/Grid/Grid.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: 'Grid',
@@ -101,7 +101,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -117,7 +117,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'CSS Grid-based layout w/ responsive column support.',
   usage: {

package/src/Grid/Grid.tsx

@@ -12,7 +12,7 @@
  * - /packages/core/src/Grid/Grid.doc.mjs
  * - /packages/core/src/Grid/Grid.test.tsx
  * - /apps/storybook/stories/Grid.stories.tsx
- * - /packages/cli/templates/blocks/components/Grid/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Grid/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';

package/src/Grid/GridSpan.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: 'GridSpan',

package/src/Grid/GridSpan.tsx

@@ -10,7 +10,7 @@
  * - /packages/core/src/Grid/Grid.doc.mjs
  * - /packages/core/src/Grid/Grid.test.tsx
  * - /apps/storybook/stories/Grid.stories.tsx
- * - /packages/cli/templates/blocks/components/Grid/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Grid/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';

package/src/HStack/HStack.tsx

@@ -9,7 +9,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Stack/Stack.doc.mjs
  * - /packages/core/src/HStack/HStack.test.tsx
- * - /packages/cli/templates/blocks/components/HStack/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/HStack/ (showcase blocks)
  */
 
 import {Stack, type StackProps} from '../Stack/Stack';

package/src/Heading/Heading.tsx

@@ -13,8 +13,8 @@
  * - /packages/core/src/Heading/Heading.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Text/index.ts (exports if types change)
  * - /apps/storybook/stories/Text.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Heading/ (showcase blocks)
- * - /packages/cli/templates/blocks/components/Text/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Heading/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Text/ (showcase blocks)
  */
 
 import {lazy, Suspense, useRef, type ReactNode} from 'react';
@@ -41,6 +41,7 @@ import {
   truncationTooltipStyles,
 } from '../Text/text.stylex';
 import {useTruncation} from '../Text/useTruncation';
+import {resolveStyleColor} from '../Text/Text';
 import type {LayerPlacement} from '../Layer';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
@@ -251,7 +252,7 @@ export function Heading({
         {...mergeProps(
           themeProps('heading', {level, color, ...(type && {type})}),
           stylex.props(
-            colorStyles[color],
+            colorStyles[resolveStyleColor(color)],
             type ? sizeByTypeStyles[type] : sizeByLevelStyles[level],
             type && defaultWeightByTypeStyles[type],
             // Display: use truncation styles when maxLines > 0

package/src/HoverCard/HoverCard.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: 'HoverCard',
@@ -125,7 +125,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'HoverCard',
   displayName: 'Hover Card',
@@ -234,7 +234,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Hover/focus triggered overlay for displaying rich, interactive content anchored to trigger element.',

package/src/HoverCard/HoverCard.tsx

@@ -12,7 +12,7 @@
  * - /packages/core/src/HoverCard/HoverCard.test.tsx
  * - /packages/core/src/HoverCard/index.ts
  * - /apps/storybook/stories/HoverCard.stories.tsx
- * - /packages/cli/templates/blocks/components/HoverCard/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/HoverCard/ (showcase blocks)
  */
 
 import {useCallback, useRef, type ReactElement, type ReactNode} from 'react';

package/src/HoverCard/useHoverCard.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useHoverCard',
   displayName: 'useHoverCard',
@@ -43,7 +43,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description: 'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
   paramDescriptions: {

package/src/HoverCard/useHoverCard.tsx

@@ -34,7 +34,6 @@ import {
   radiusVars,
   spacingVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
@@ -469,6 +468,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
       props?: Omit<ContextRenderProps, 'positioning'>,
     ): ReactNode => {
       const renderPlacement = props?.placement ?? placement;
+      const themeClassName = themeProps('hovercard').className;
       const renderProps = {
         placement: renderPlacement,
         alignment: props?.alignment ?? alignment,
@@ -477,7 +477,19 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
         // are non-modal, so group is honest semantics without a name.
         role: label ? 'dialog' : 'group',
         'aria-label': label || undefined,
-        xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
+        // Consumer surface style props land on the layer container — the
+        // themed surface (bg/radius/shadow) where the theme class lives — so
+        // customizing the card targets the same element as the theme. The inner
+        // span keeps `styles.content` for padding.
+        xstyle: [
+          popoverXstyle,
+          layerAnimations[renderPlacement],
+          props?.xstyle,
+        ],
+        className: props?.className
+          ? `${themeClassName} ${props.className}`
+          : themeClassName,
+        style: props?.style,
         // 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,
@@ -485,7 +497,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
 
       return layer.render(
         <span
-          {...mergeProps(themeProps('hovercard'), stylex.props(styles.content))}
+          {...stylex.props(styles.content)}
           onMouseEnter={() => {
             isHoveringContentRef.current = true;
             clearTimeouts();

package/src/Icon/Icon.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: 'Icon',
@@ -39,6 +39,12 @@ export const docs = {
       type: 'string',
       description: 'Accessible name for a MEANINGFUL, standalone icon (a status glyph or icon-only indicator with no adjacent text). Setting it exposes the icon to screen readers as role="img" with this text as the accessible name (aria-label) and removes the default aria-hidden. Omit it (default) for decorative icons and the icon stays hidden from assistive tech (aria-hidden="true"). This is the accessible-name / alt-text prop for icons: one prop instead of manually setting aria-label + role + aria-hidden. An empty string is treated as decorative. Do not set it when an interactive parent (Button, IconButton, link) already names the control.',
     },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for customization (color, size, opacity). Folded into the icon\'s own stylex.props() call so it composes with the base color/size styles. Must be a stylex.create() value, not an inline style object like style={{}}.',
+    },
   ],
   theming: {
     targets: [
@@ -62,7 +68,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Icon',
   displayName: 'Icon',
@@ -90,6 +96,12 @@ export const docsZh = {
       type: 'string',
       description: '有含义的独立图标的可访问名称（无相邻文字的状态图标或纯图标指示器）。设置后会将图标以 role="img" 暴露给辅助技术，并以该文本作为可访问名称（aria-label），同时移除默认的 aria-hidden。省略（默认）用于装饰性图标，图标对辅助技术保持隐藏（aria-hidden="true"）。空字符串按装饰性处理。当交互式父元素（Button、IconButton、链接）已命名该控件时请勿设置。',
     },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        '用于自定义的 StyleX 样式（颜色、尺寸、不透明度）。会并入图标自身的 stylex.props() 调用，从而与基础的颜色/尺寸样式组合。必须是 stylex.create() 的值，而不是像 style={{}} 这样的内联样式对象。',
+    },
   ],
   theming: {
     targets: [
@@ -112,7 +124,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Renders icons w/ Astryx design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
@@ -136,5 +148,6 @@ export const docsDense = {
     color: 'Color variant mapped to Astryx icon color tokens.',
     size: 'Icon size.',
     label: 'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
+    xstyle: 'StyleX styles (color, size, opacity) via stylex.create(); composes with the base color/size styles.',
   },
 };