@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/Carousel/Carousel.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
     anatomy: [
       {name: 'Scroll container', required: true, description: 'The horizontal overflow area that holds all items.'},
       {name: 'Items', required: true, description: 'The children rendered in a row. Each item is animated with a scroll-driven scale effect.'},
-      {name: 'Fade edges', required: true, description: 'Gradient fades on the left and right edges that indicate more content is available.'},
+      {name: 'Fade edges', required: false, description: 'Gradient fades on the left and right edges that indicate more content is available. Enabled by default, disable with hasEdgeFade={false}.'},
       {name: 'Navigation buttons', required: false, description: 'Prev/next buttons that appear on hover. Enabled by default, disable with hasButtons={false}.'},
     ],
   },
@@ -29,7 +29,9 @@ export const docs = {
     {name: 'children', type: 'ReactNode', description: 'Carousel items rendered in a horizontal scroll container.', required: true},
     {name: 'gap', type: "0 | 0.5 | 1 | 1.5 | 2 | 3 | 4", description: 'Gap between items using the spacing token scale.', default: '1'},
     {name: 'hasButtons', type: 'boolean', description: 'Show prev/next navigation buttons on hover (desktop only).', default: 'true'},
+    {name: 'hasEdgeFade', type: 'boolean', description: 'Show a gradient edge-fade mask when content overflows, signalling that more items exist off-screen.', default: 'true'},
     {name: 'hasSnap', type: 'boolean', description: 'Enable scroll-snap so each child snaps to the start edge.', default: 'false'},
+    {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inline padding inside the scroll container, with matching scroll-padding so snap points align to the content edge.'},
     {name: 'aria-label', type: 'string', description: 'Accessible label for the carousel region.', default: "\'Carousel\'"},
     {name: 'ref', type: 'React.Ref<HTMLDivElement>', description: 'Ref forwarded to the root element.'},
     {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value.'},
@@ -71,7 +73,9 @@ export const docsZh = {
     children: '在水平滚动容器中渲染的轮播项目。',
     gap: '使用间距令牌比例的项目间距。',
     hasButtons: '悬停时显示上一个/下一个导航按钮（仅桌面端）。',
+    hasEdgeFade: '内容溢出时显示渐变边缘遮罩，提示屏幕外还有更多项目。',
     hasSnap: '启用滚动吸附，使每个子元素吸附到起始边缘。',
+    padding: '滚动容器内的内联内边距，并设置匹配的 scroll-padding，使吸附点与内容边缘对齐。',
     'aria-label': '轮播区域的无障碍标签。',
   },
 };
@@ -95,7 +99,9 @@ export const docsDense = {
     children: 'carousel items in horizontal scroll',
     gap: 'item spacing via spacing token scale',
     hasButtons: 'prev/next buttons on hover (desktop)',
+    hasEdgeFade: 'gradient edge-fade mask on overflow',
     hasSnap: 'scroll-snap; children snap to start edge',
+    padding: 'inline padding; scroll-padding keeps snap points on content edge',
     'aria-label': 'accessible label for carousel region',
     'data-testid': 'test selector for automated testing frameworks',
   },

package/src/Carousel/Carousel.test.tsx

@@ -78,4 +78,24 @@ describe('Carousel', () => {
     expect(screen.getByLabelText('Scroll left')).toBeInTheDocument();
     expect(screen.getByLabelText('Scroll right')).toBeInTheDocument();
   });
+
+  it('disables edge scroll buttons instead of removing them from the tab order', () => {
+    // In jsdom there is no measurable overflow, so both edges are at rest and
+    // the scroll buttons are in their hidden/inert state. They must stay
+    // mounted but be disabled — a disabled <button> is skipped by the tab
+    // order and hidden from the a11y tree, so keyboard users don't focus an
+    // invisible control (WCAG 2.4.7).
+    render(
+      <Carousel aria-label="Edge state">
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </Carousel>,
+    );
+    const left = screen.getByLabelText('Scroll left');
+    const right = screen.getByLabelText('Scroll right');
+    expect(left).toBeInTheDocument();
+    expect(right).toBeInTheDocument();
+    expect(left).toBeDisabled();
+    expect(right).toBeDisabled();
+  });
 });

package/src/Carousel/Carousel.tsx

@@ -295,9 +295,16 @@ export function Carousel({
     const firstChild = el.firstElementChild as HTMLElement | null;
     const itemWidth = firstChild ? firstChild.offsetWidth : 0;
     const amount = el.clientWidth - itemWidth * 0.5;
+    // Respect the user's reduced-motion preference — mirrors the CSS
+    // scroll-behavior override so button-driven scrolling doesn't animate
+    // for users who opted out of motion.
+    const prefersReducedMotion =
+      typeof window !== 'undefined' &&
+      typeof window.matchMedia === 'function' &&
+      window.matchMedia('(prefers-reduced-motion: reduce)').matches;
     el.scrollBy({
       left: direction * Math.max(amount, itemWidth),
-      behavior: 'smooth',
+      behavior: prefersReducedMotion ? 'auto' : 'smooth',
     });
   }, []);
 
@@ -360,6 +367,11 @@ export function Carousel({
                 variant="ghost"
                 size="sm"
                 isIconOnly
+                // Disabled when there's nothing to scroll toward. Keeps the
+                // button mounted (stable layout/focus) but removes it from the
+                // tab order and a11y tree while it's visually hidden, so
+                // keyboard users don't land on an invisible control.
+                isDisabled={!overflowStart}
                 onClick={() => scrollBy(-1)}
                 xstyle={styles.buttonRadiusOverride}
               />
@@ -376,6 +388,9 @@ export function Carousel({
                 variant="ghost"
                 size="sm"
                 isIconOnly
+                // See "Scroll left" — disabled while visually hidden so the
+                // button stays mounted but out of the tab order / a11y tree.
+                isDisabled={!overflowEnd}
                 onClick={() => scrollBy(1)}
                 xstyle={styles.buttonRadiusOverride}
               />

package/src/Center/Center.doc.mjs

@@ -18,14 +18,24 @@ export const docs = {
     },
     {
       name: 'width',
-      type: 'number | string',
+      type: 'SizeValue',
       description: 'Container width (px or CSS value).',
     },
     {
       name: 'height',
-      type: 'number | string',
+      type: 'SizeValue',
       description: 'Container height (px or CSS value).',
     },
+    {
+      name: 'maxWidth',
+      type: 'SizeValue',
+      description: 'Maximum container width (px or CSS value).',
+    },
+    {
+      name: 'minHeight',
+      type: 'SizeValue',
+      description: 'Minimum container height (px or CSS value).',
+    },
     {
       name: 'isInline',
       type: 'boolean',

package/src/Center/Center.tsx

@@ -39,15 +39,21 @@ const styles = stylex.create({
 
 // Dynamic styles for sizing props
 const dynamicStyles = stylex.create({
-  sizing: (width: SizeValue | null, height: SizeValue | null) => ({
+  sizing: (
+    width: SizeValue | null,
+    height: SizeValue | null,
+    maxWidth: SizeValue | null,
+    minHeight: SizeValue | null,
+  ) => ({
     width,
     height,
+    maxWidth,
+    minHeight,
   }),
 });
 
 export type CenterAxis = 'both' | 'horizontal' | 'vertical';
 
-
 export interface CenterProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLDivElement>;
@@ -72,6 +78,18 @@ export interface CenterProps extends BaseProps<HTMLDivElement> {
    */
   height?: SizeValue;
 
+  /**
+   * Maximum width of the container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  maxWidth?: SizeValue;
+
+  /**
+   * Minimum height of the container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  minHeight?: SizeValue;
+
   /**
    * Whether to make the container inline-flex (useful for text/icons).
    * @default false
@@ -101,6 +119,8 @@ export function Center({
   axis = 'both',
   width,
   height,
+  maxWidth,
+  minHeight,
   isInline = false,
   children,
   xstyle,
@@ -115,7 +135,12 @@ export function Center({
       isInline ? styles.inline : styles.base,
       (axis === 'both' || axis === 'vertical') && styles.alignItemsCenter,
       (axis === 'both' || axis === 'horizontal') && styles.justifyContentCenter,
-      dynamicStyles.sizing(width ?? null, height ?? null),
+      dynamicStyles.sizing(
+        width ?? null,
+        height ?? null,
+        maxWidth ?? null,
+        minHeight ?? null,
+      ),
       xstyle,
     ),
     className,

package/src/Chat/ChatComposer.doc.mjs

@@ -7,6 +7,9 @@ export const docs = {
   subComponentOf: 'Chat',
   displayName: 'Chat Composer',
   description: 'Layout shell for a chat composer. Arranges named slots (drawer, header, input, footer, send) with page-radius container, hover/focus shadows, and concentric inner radius for child elements.',
+  playground: {
+    wrapper: {component: 'Stack', props: {width: 480}},
+  },
   props: [
     {
       name: 'onSubmit',

package/src/Chat/ChatComposerDrawer.doc.mjs

@@ -8,6 +8,18 @@ export const docs = {
   displayName: 'Chat Composer Drawer',
   isHiddenFromOverview: true,
   description: "Collapsible drawer panel that sits above the chat input inside ChatComposer. Pass it to the composer's `drawer` slot to show attachments, context chips, or any supplementary content. When `count` is provided the drawer gains a collapse toggle: collapsed state shows a badge and label, expanded state shows all children.",
+  playground: {
+    wrapper: {component: 'Stack', props: {width: 480}},
+    defaults: {
+      count: 3,
+      label: 'Attachments',
+      children: [
+        {__element: 'Token', props: {label: 'design-spec.pdf'}},
+        {__element: 'Token', props: {label: 'api-schema.json'}},
+        {__element: 'Token', props: {label: 'screenshot.png'}},
+      ],
+    },
+  },
   props: [
     {
       name: 'children',

package/src/Chat/ChatMessageList.doc.mjs

@@ -45,6 +45,12 @@ export const docs = {
       type: 'SpacingStep',
       description: 'Gap between top-level message rows. Defaults to the selected density; override for LLM event streams or independent rows that need different spacing from density.',
     },
+    {
+      name: 'isStreaming',
+      type: 'boolean',
+      description: 'Whether an assistant message is actively streaming. Marks the log aria-busy so screen readers wait and announce the completed message once instead of re-announcing partial text on every token.',
+      default: 'false',
+    },
   ],
 };
 
@@ -59,6 +65,7 @@ export const docsZh = {
     scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
     density: '视觉密度，通过上下文传递给子消息。',
     gap: '顶层消息行之间的间距。默认跟随密度；当 LLM 事件流等独立行需要不同间距时可覆盖。',
+    isStreaming: '是否有助手消息正在流式输出。标记日志为 aria-busy，让屏幕阅读器等待并在完成后一次性播报，而不是每个 token 都重复播报。',
   },
 };
 
@@ -73,5 +80,6 @@ export const docsDense = {
     scrollToTopAction: 'async action at scroll top; load older msgs',
     density: 'visual density; flows to children via context',
     gap: 'top-level row gap; defaults to density spacing; override for independent LLM/tool rows',
+    isStreaming: 'assistant streaming? marks log aria-busy so SR announces the completed msg once',
   },
 };

package/src/Chat/ChatMessageList.test.tsx

@@ -28,6 +28,24 @@ describe('ChatMessageList', () => {
     expect(el.getAttribute('role')).toBe('log');
   });
 
+  it('is not aria-busy by default', () => {
+    render(
+      <ChatMessageList data-testid="list">
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(screen.getByTestId('list')).not.toHaveAttribute('aria-busy');
+  });
+
+  it('marks the log aria-busy while streaming', () => {
+    render(
+      <ChatMessageList data-testid="list" isStreaming>
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(screen.getByTestId('list')).toHaveAttribute('aria-busy', 'true');
+  });
+
   it('renders empty state when no children', () => {
     render(
       <ChatMessageList emptyState={<div>No messages yet</div>}>

package/src/Chat/ChatMessageList.tsx

@@ -72,6 +72,20 @@ export interface ChatMessageListProps extends BaseProps<HTMLDivElement> {
    * be grouped) and row spacing should be tuned separately from density.
    */
   gap?: SpacingStep;
+
+  /**
+   * Whether an assistant message is actively streaming into the list.
+   *
+   * The list is a `role="log"` / `aria-live="polite"` region, so while a
+   * message streams in token-by-token, screen readers would otherwise
+   * re-announce the accumulating partial text on every mutation. Set
+   * `isStreaming` to `true` for the duration of a stream: it marks the log
+   * `aria-busy="true"` so assistive tech waits and announces the completed
+   * message once, when `isStreaming` returns to `false`.
+   *
+   * @default false
+   */
+  isStreaming?: boolean;
 }
 
 // =============================================================================
@@ -190,6 +204,7 @@ export function ChatMessageList({
   scrollToTopAction,
   density = 'balanced',
   gap,
+  isStreaming = false,
   xstyle,
   className,
   style,
@@ -252,6 +267,7 @@ export function ChatMessageList({
         ref={ref}
         role="log"
         aria-live="polite"
+        aria-busy={isStreaming || undefined}
         tabIndex={0}
         data-testid={testId}
         {...mergeProps(

package/src/Chat/useTriggerMenu.tsx

@@ -296,6 +296,9 @@ export function useTriggerMenu(
     hasLightDismiss: true,
     hasCloseButton: false,
     hasAutoFocus: false,
+    // The popup's own role="listbox" is the exposed semantics; focus stays in
+    // the contenteditable composer, so a modal dialog wrapper is incorrect.
+    role: 'none',
   });
 
   // Cleanup on unmount

package/src/CheckboxInput/CheckboxInput.doc.mjs

@@ -63,6 +63,19 @@ export const docs = {
       description: 'Whether the checkbox is disabled.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
+    {
+      name: 'isReadOnly',
+      type: 'boolean',
+      description:
+        'Whether the checkbox is read-only. Displays the current state at full opacity but prevents interaction. Unlike `isDisabled`, read-only checkboxes are not visually dimmed.',
+      default: 'false',
+    },
     {
       name: 'isOptional',
       type: 'boolean',
@@ -117,6 +130,7 @@ export const docs = {
       { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
       { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
       { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
+      { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
     anatomy: [
       { name: 'Checkbox', required: true, description: 'The check box itself: unchecked, checked, or indeterminate.' },
@@ -139,6 +153,7 @@ export const docsZh = {
       { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
       { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
       { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
+      { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
   props: [
@@ -156,6 +171,8 @@ export const docsZh = {
     },
     {name: 'isLoading', type: 'boolean', description: '复选框是否处于加载状态。显示旋转器并阻止交互。', default: 'false'},
     {name: 'isDisabled', type: 'boolean', description: '复选框是否禁用。', default: 'false'},
+    {name: 'disabledMessage', type: 'string', description: 'Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.'},
+    {name: 'isReadOnly', type: 'boolean', description: '复选框是否为只读。以完整不透明度显示当前状态但阻止交互。与 isDisabled 不同，只读复选框不会变暗。', default: 'false'},
     {name: 'isOptional', type: 'boolean', description: '字段是否可选。与 isRequired 互斥。', default: 'false'},
     {name: 'isRequired', type: 'boolean', description: '复选框是否必填。与 isOptional 互斥。', default: 'false'},
     {name: 'size', type: "'sm' | 'md'", description: '复选框尺寸。sm 用于紧凑布局，md 为默认。', default: "'md'"},
@@ -192,6 +209,7 @@ export const docsDense = {
       { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
       { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
       { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
+      { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
   propDescriptions: {

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -9,41 +9,56 @@
  * SYNC: When CheckboxInput.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {CheckboxInput} from './CheckboxInput';
 
+// Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
+// reflects its open state via a `popover-open` attribute the tests can assert.
+beforeEach(() => {
+  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+    this.setAttribute('popover-open', '');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'open'});
+    this.dispatchEvent(event);
+  });
+  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+    this.removeAttribute('popover-open');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'closed'});
+    this.dispatchEvent(event);
+  });
+  const originalMatches = HTMLElement.prototype.matches;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (HTMLElement.prototype as any).matches = function (
+    selector: string,
+  ): boolean {
+    if (selector === ':popover-open') {
+      return this.hasAttribute('popover-open');
+    }
+    return originalMatches.call(this, selector);
+  };
+});
+
 describe('CheckboxInput', () => {
   it('renders with label', () => {
     render(
-      <CheckboxInput
-        label="Accept terms"
-        value={false}
-        onChange={() => {}}
-      />,
+      <CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,
     );
     expect(screen.getByLabelText('Accept terms')).toBeInTheDocument();
   });
 
   it('renders as unchecked by default', () => {
     render(
-      <CheckboxInput
-        label="Accept terms"
-        value={false}
-        onChange={() => {}}
-      />,
+      <CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,
     );
     expect(screen.getByRole('checkbox')).not.toBeChecked();
   });
 
   it('renders as checked when value prop is true', () => {
     render(
-      <CheckboxInput
-        label="Accept terms"
-        value={true}
-        onChange={() => {}}
-      />,
+      <CheckboxInput label="Accept terms" value={true} onChange={() => {}} />,
     );
     expect(screen.getByRole('checkbox')).toBeChecked();
   });
@@ -182,11 +197,7 @@ describe('CheckboxInput', () => {
 
   it('shows label visually by default', () => {
     render(
-      <CheckboxInput
-        label="Accept terms"
-        value={false}
-        onChange={() => {}}
-      />,
+      <CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,
     );
     const label = screen.getByText('Accept terms');
     expect(label).toBeVisible();
@@ -204,7 +215,7 @@ describe('CheckboxInput', () => {
     expect(screen.getByRole('checkbox')).toHaveAttribute('aria-busy', 'true');
   });
 
-  it('sets aria-checked="mixed" for indeterminate state', () => {
+  it('exposes indeterminate state via the native indeterminate property', () => {
     render(
       <CheckboxInput
         label="Select all"
@@ -212,10 +223,15 @@ describe('CheckboxInput', () => {
         onChange={() => {}}
       />,
     );
-    expect(screen.getByRole('checkbox')).toHaveAttribute(
-      'aria-checked',
-      'mixed',
-    );
+    const checkbox = screen.getByRole('checkbox');
+    // Native checkboxes expose mixed state through the DOM indeterminate
+    // property, which browsers map to aria-checked="mixed". A redundant
+    // aria-checked attribute is intentionally NOT set (forms-16).
+    expect(checkbox).toBeInstanceOf(HTMLInputElement);
+    if (checkbox instanceof HTMLInputElement) {
+      expect(checkbox.indeterminate).toBe(true);
+    }
+    expect(checkbox).not.toHaveAttribute('aria-checked');
   });
 
   it('renders semantic labelIcon names as icons', () => {
@@ -247,4 +263,133 @@ describe('CheckboxInput', () => {
       'true',
     );
   });
+
+  describe('disabledMessage', () => {
+    const h = {hidden: true} as const;
+
+    function getRow(): HTMLElement {
+      return screen.getByRole('checkbox', h).closest('div')!.parentElement!;
+    }
+
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Terms are managed by your administrator"
+        />,
+      );
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent(
+        'Terms are managed by your administrator',
+      );
+      fireEvent.mouseEnter(getRow());
+      await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+      fireEvent.mouseLeave(getRow());
+      await waitFor(() => expect(tooltip).not.toHaveAttribute('popover-open'));
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Terms are managed by your administrator"
+        />,
+      );
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('checkbox', h)).toHaveFocus();
+      await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          disabledMessage="Terms are managed by your administrator"
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the checkbox focusable via aria-disabled when a reason is provided', () => {
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Terms are managed by your administrator"
+        />,
+      );
+      const checkbox = screen.getByRole('checkbox', h);
+      expect(checkbox).not.toBeDisabled();
+      expect(checkbox).toHaveAttribute('aria-disabled', 'true');
+    });
+
+    it('links the reason tooltip via aria-describedby', () => {
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Terms are managed by your administrator"
+        />,
+      );
+      const checkbox = screen.getByRole('checkbox', h);
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(checkbox.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks toggling while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={onChange}
+          isDisabled
+          disabledMessage="Terms are managed by your administrator"
+        />,
+      );
+      const checkbox = screen.getByRole('checkbox', h);
+      await user.click(checkbox);
+      expect(onChange).not.toHaveBeenCalled();
+      expect(checkbox).not.toBeChecked();
+    });
+
+    it('remains natively disabled when disabled without a reason', () => {
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.getByRole('checkbox')).toBeDisabled();
+    });
+  });
 });