@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -167,6 +167,59 @@ describe('CheckboxInput', () => {
     expect(handleChange).not.toHaveBeenCalled();
   });
 
+  it('forwards data-testid to the input', () => {
+    render(
+      <CheckboxInput
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+        data-testid="accept-terms-checkbox"
+      />,
+    );
+    expect(screen.getByTestId('accept-terms-checkbox')).toBe(
+      screen.getByRole('checkbox'),
+    );
+  });
+
+  it('forwards arbitrary data-* attributes to the input', () => {
+    render(
+      <CheckboxInput
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+        data-tracking-id="checkbox-42"
+      />,
+    );
+    expect(screen.getByRole('checkbox')).toHaveAttribute(
+      'data-tracking-id',
+      'checkbox-42',
+    );
+  });
+
+  it('does not let rest props override checked, disabled, or type', () => {
+    // Not part of CheckboxInputProps; spread (rather than named attributes)
+    // to sidestep JSX excess-property checks the same way a real caller's
+    // spread rest-props object would arrive untyped at runtime.
+    const foreignAttrs: Record<string, unknown> = {
+      checked: false,
+      disabled: false,
+      type: 'text',
+    };
+    render(
+      <CheckboxInput
+        {...foreignAttrs}
+        label="Accept terms"
+        value={true}
+        onChange={() => {}}
+        isDisabled
+      />,
+    );
+    const checkbox = screen.getByRole('checkbox');
+    expect(checkbox).toBeChecked();
+    expect(checkbox).toBeDisabled();
+    expect(checkbox).toHaveAttribute('type', 'checkbox');
+  });
+
   it('forwards ref correctly', () => {
     const ref = vi.fn();
     render(
@@ -396,7 +449,12 @@ describe('CheckboxInput', () => {
     it('submits under htmlName when checked', () => {
       const {container} = render(
         <form>
-          <CheckboxInput label="Terms" htmlName="terms" value={true} onChange={() => {}} />
+          <CheckboxInput
+            label="Terms"
+            htmlName="terms"
+            value={true}
+            onChange={() => {}}
+          />
         </form>,
       );
       const data = new FormData(container.querySelector('form')!);
@@ -416,16 +474,25 @@ describe('CheckboxInput', () => {
           />
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
 
     it('submits nothing when unchecked', () => {
       const {container} = render(
         <form>
-          <CheckboxInput label="Terms" htmlName="terms" value={false} onChange={() => {}} />
+          <CheckboxInput
+            label="Terms"
+            htmlName="terms"
+            value={false}
+            onChange={() => {}}
+          />
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
   });
 });

package/src/CheckboxInput/CheckboxInput.tsx

@@ -395,6 +395,7 @@ export function CheckboxInput({
   className,
   style,
   ref,
+  ...rest
 }: CheckboxInputProps) {
   const id = useId();
   const descriptionID = useId();
@@ -484,6 +485,7 @@ export function CheckboxInput({
         )}>
         <div {...stylex.props(styles.checkboxWrapper, wrapperSizeStyles[size])}>
           <input
+            {...rest}
             ref={mergeRefs(
               ref,
               indeterminateRef,

package/src/CheckboxList/CheckboxList.test.tsx

@@ -135,6 +135,25 @@ describe('CheckboxList', () => {
     expect(handleChange).toHaveBeenCalledWith(['b']);
   });
 
+  it('fires a consumer onClick on an item in addition to toggling', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    const handleClick = vi.fn();
+    render(
+      <CheckboxList label="Preferences" value={['a']} onChange={handleChange}>
+        <CheckboxListItem label="Option A" value="a" />
+        <CheckboxListItem label="Option B" value="b" onClick={handleClick} />
+      </CheckboxList>,
+    );
+
+    // Click the interactive row (invisible-button pattern), which is where the
+    // composed onClick lives — not the inner checkbox.
+    await user.click(screen.getByRole('button', {name: 'Option B'}));
+
+    expect(handleClick).toHaveBeenCalledTimes(1);
+    expect(handleChange).toHaveBeenCalledWith(['a', 'b']);
+  });
+
   it('disables all checkboxes when group isDisabled is true', () => {
     render(
       <CheckboxList

package/src/CheckboxList/CheckboxListItem.tsx

@@ -16,11 +16,12 @@
  * - /packages/cli/templates/blocks/components/CheckboxList/ (showcase blocks)
  */
 
-import {use, type ReactNode} from 'react';
+import {use, type MouseEvent, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
+import {composeEventHandlers} from '../utils';
 import {CheckboxInput} from '../CheckboxInput/CheckboxInput';
 import {ListItem} from '../List/ListItem';
 import {ListContext} from '../List/ListContext';
@@ -128,6 +129,7 @@ export function CheckboxListItem({
   xstyle,
   className,
   style,
+  onClick: onClickProp,
   ...restProps
 }: CheckboxListItemProps) {
   const ctx = use(CheckboxListContext);
@@ -200,7 +202,14 @@ export function CheckboxListItem({
       description={description}
       endContent={endContent}
       isDisabled={effectiveDisabled}
-      onClick={isInteractive ? handleToggle : undefined}
+      onClick={
+        isInteractive || onClickProp
+          ? composeEventHandlers<MouseEvent>(
+              onClickProp as ((event: MouseEvent) => void) | undefined,
+              isInteractive ? handleToggle : undefined,
+            )
+          : undefined
+      }
       aria-busy={isBusy || undefined}
       xstyle={
         [

package/src/Citation/Citation.doc.mjs

@@ -88,6 +88,11 @@ export const docs = {
       default: "'label'",
     },
   ],
+  theming: {
+    targets: [
+      {className: 'astryx-citation', visualProps: ['variant']},
+    ],
+  },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */

package/src/ClickableCard/ClickableCard.tsx

@@ -31,7 +31,12 @@
 import {type ReactNode, type MouseEvent, useRef, type Ref} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
-import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';
+import {
+  borderVars,
+  colorVars,
+  durationVars,
+  easeVars,
+} from '../theme/tokens.stylex';
 import type {SizeValue, SpacingStep} from '../utils/types';
 import {mergeProps, mergeRefs} from '../utils';
 import {Card} from '../Card/Card';
@@ -66,7 +71,6 @@ const styles = stylex.create({
       content: '""',
       position: 'absolute',
       inset: 0,
-      borderRadius: 'inherit',
       pointerEvents: 'none',
       transitionProperty: 'background-color',
       transitionDuration: durationVars['--duration-fast'],
@@ -84,6 +88,38 @@ const styles = stylex.create({
       },
     },
   },
+  // Borderless variants (everything except `default`): drop the transparent
+  // 1px border Card applies. The overlay is inset to the padding box — inside
+  // that border — so a transparent border strip stays untinted on hover and
+  // reads as a faint ring. With no border, the overlay covers the full box
+  // edge-to-edge and the ring disappears.
+  borderless: {
+    borderWidth: 0,
+  },
+  // Bordered variant (`default`): draw the 1px border *within* the padding by
+  // subtracting the border width from every side. Total inset (border +
+  // padding) then equals the borderless variants' padding, so content geometry
+  // and outer dimensions stay identical across all variants. The border rests
+  // at the subtle token and emphasizes on hover.
+  bordered: {
+    borderColor: colorVars['--color-border'],
+    paddingInlineStart: `calc(var(--container-padding-inline-start) - ${borderVars['--border-width']})`,
+    paddingInlineEnd: `calc(var(--container-padding-inline-end) - ${borderVars['--border-width']})`,
+    paddingBlockStart: `calc(var(--container-padding-block-start) - ${borderVars['--border-width']})`,
+    paddingBlockEnd: `calc(var(--container-padding-block-end) - ${borderVars['--border-width']})`,
+    transitionProperty: 'border-color',
+    transitionDuration: durationVars['--duration-fast'],
+    transitionTimingFunction: easeVars['--ease-standard'],
+  },
+  // Emphasize the bordered variant's border on hover. Guarded by
+  // @media (hover: hover) so touch devices don't get a stuck hover state.
+  borderedHoverOnPointer: {
+    '@media (hover: hover)': {
+      ':hover': {
+        borderColor: colorVars['--color-border-emphasized'],
+      },
+    },
+  },
   disabled: {
     cursor: 'not-allowed',
     opacity: 0.5,
@@ -248,6 +284,11 @@ export function ClickableCard({
 
   const isLink = href != null;
 
+  // Only the `default` variant has a visible border. Card draws a transparent
+  // 1px border on every other variant purely to avoid layout jitter; we drop
+  // it here so the hover overlay covers the full box with no untinted ring.
+  const hasBorder = variant === 'default';
+
   return (
     <Card
       ref={mergeRefs(ref, containerRef)}
@@ -264,8 +305,10 @@ export function ClickableCard({
         [
           styles.interactive,
           styles.focusWithin,
+          hasBorder ? styles.bordered : styles.borderless,
           !isDisabled && styles.overlay,
           !isDisabled && styles.hoverOnPointer,
+          !isDisabled && hasBorder && styles.borderedHoverOnPointer,
           isDisabled && styles.disabled,
           xstyleProp,
         ] as unknown as StyleXStyles

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -90,6 +90,11 @@ export const docs = {
       type: '(code: string, language: string) => Array<{type: string; start: number; end: number}>',
       description: 'Custom tokenizer override for unsupported languages.',
     },
+    {
+      name: 'syntaxTheme',
+      type: 'SyntaxThemeDefinition',
+      description: 'Per-instance syntax theme override. Shorthand for wrapping the block in <SyntaxTheme theme={...}>. Accepts a preset from @astryxdesign/core/theme/syntax or a theme created with defineSyntaxTheme(). Defaults to the nearest SyntaxTheme ancestor or the theme-level syntax colors.',
+    },
     {
       name: 'isCollapsible',
       type: 'boolean',
@@ -135,8 +140,8 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-code'},
-      {className: 'astryx-codeblock', visualProps: ['size', 'language']},
+      {className: 'astryx-code', visualProps: ['color']},
+      {className: 'astryx-codeblock', visualProps: ['size', 'language', 'container']},
     ],
   },
   usage: {

package/src/CodeBlock/CodeBlock.test.tsx

@@ -3,15 +3,21 @@
 /**
  * @file CodeBlock.test.tsx
  * @input Uses vitest, @testing-library/react, CodeBlock component
- * @output Unit tests for CodeBlock (copy button, collapse, scroll region a11y)
+ * @output Unit tests for CodeBlock (copy button, collapse, scroll region a11y, syntaxTheme)
  * @position Testing; validates CodeBlock implementation
  *
  * SYNC: When CodeBlock.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {act, render, screen, fireEvent, waitFor} from '@testing-library/react';
 import {CodeBlock} from './CodeBlock';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+import {dracula} from '../theme/syntax';
+
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
 
 // A code sample long enough to exceed the default collapsible threshold (10).
 const LONG_CODE = Array.from(
@@ -27,6 +33,10 @@ describe('CodeBlock', () => {
     });
   });
 
+  afterEach(() => {
+    __resetLiveRegionsForTest();
+  });
+
   it('renders the code', () => {
     render(<CodeBlock code="const x = 1;" language="javascript" />);
     expect(screen.getByText(/const/)).toBeInTheDocument();
@@ -53,6 +63,50 @@ describe('CodeBlock', () => {
     expect(navigator.clipboard.writeText).toHaveBeenCalledWith('const x = 1;');
   });
 
+  it('announces "Copied" to a polite live region after copying', async () => {
+    render(<CodeBlock code="const x = 1;" language="javascript" />);
+    const copyButton = screen.getByRole('button', {name: 'Copy code'});
+    fireEvent.click(copyButton);
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('Copied');
+    });
+  });
+
+  it('keeps the copied indicator a full 2s after a rapid re-copy', async () => {
+    vi.useFakeTimers();
+    try {
+      render(<CodeBlock code="const x = 1;" language="javascript" />);
+      fireEvent.click(screen.getByRole('button', {name: 'Copy code'}));
+      // Flush the async clipboard write.
+      await act(async () => {});
+      expect(screen.getByRole('button', {name: 'Copied'})).toBeInTheDocument();
+
+      // 1.5s later the user copies again.
+      act(() => {
+        vi.advanceTimersByTime(1500);
+      });
+      fireEvent.click(screen.getByRole('button', {name: 'Copied'}));
+      await act(async () => {});
+
+      // 600ms after the second copy (2.1s after the first): the first
+      // click's timer must not have reverted the indicator early.
+      act(() => {
+        vi.advanceTimersByTime(600);
+      });
+      expect(screen.getByRole('button', {name: 'Copied'})).toBeInTheDocument();
+
+      // It resets 2s after the most recent copy.
+      act(() => {
+        vi.advanceTimersByTime(1400);
+      });
+      expect(
+        screen.getByRole('button', {name: 'Copy code'}),
+      ).toBeInTheDocument();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('does NOT collapse the block when the copy button is clicked', () => {
     render(
       <CodeBlock
@@ -112,4 +166,69 @@ describe('CodeBlock', () => {
     fireEvent.click(header);
     expect(header).toHaveAttribute('aria-expanded', 'false');
   });
+
+  it('links the collapsible header to its code region via aria-controls', () => {
+    render(
+      <CodeBlock
+        code={LONG_CODE}
+        language="javascript"
+        title="example"
+        isCollapsible
+      />,
+    );
+    const header = screen
+      .getAllByRole('button')
+      .find(el => el.hasAttribute('aria-expanded'))!;
+    const controlsId = header.getAttribute('aria-controls');
+    // aria-controls must be present and point at the real code region.
+    expect(controlsId).toBeTruthy();
+    const region = document.getElementById(controlsId as string);
+    expect(region).not.toBeNull();
+    // The region contains the scrollable code body (role="group").
+    expect(region).toContainElement(screen.getByRole('group'));
+  });
+
+  it('keeps aria-controls resolvable when collapsed (region stays mounted)', () => {
+    render(
+      <CodeBlock
+        code={LONG_CODE}
+        language="javascript"
+        title="example"
+        isCollapsible
+      />,
+    );
+    const header = screen
+      .getAllByRole('button')
+      .find(el => el.hasAttribute('aria-expanded'))!;
+    fireEvent.click(header);
+    expect(header).toHaveAttribute('aria-expanded', 'false');
+    // The code region uses a CSS grid animation to collapse, so it stays in
+    // the DOM — aria-controls stays a valid, resolvable reference (unlike a
+    // conditionally-mounted region, which would need a conditional attribute).
+    const controlsId = header.getAttribute('aria-controls');
+    expect(controlsId).toBeTruthy();
+    expect(document.getElementById(controlsId as string)).not.toBeNull();
+  });
+
+  it('applies a per-instance syntax theme via the syntaxTheme prop', () => {
+    const {container} = render(
+      <CodeBlock
+        code="const x = 1;"
+        language="javascript"
+        syntaxTheme={dracula}
+      />,
+    );
+    const wrapper = container.querySelector('[data-astryx-syntax-theme]');
+    expect(wrapper).not.toBeNull();
+    expect(wrapper).toHaveAttribute('data-astryx-syntax-theme', 'dracula');
+    expect(wrapper!.querySelector('pre')).not.toBeNull();
+  });
+
+  it('renders no syntax theme wrapper when syntaxTheme is not set', () => {
+    const {container} = render(
+      <CodeBlock code="const x = 1;" language="javascript" />,
+    );
+    expect(container.querySelector('[data-astryx-syntax-theme]')).toBeNull();
+    expect(container.firstElementChild?.tagName).toBe('PRE');
+  });
 });

package/src/CodeBlock/CodeBlock.tsx

@@ -3,7 +3,7 @@
 'use client';
 /**
  * @file CodeBlock.tsx
- * @input Uses React, StyleX, theme tokens, CSS Custom Highlight API
+ * @input Uses React, StyleX, theme tokens, CSS Custom Highlight API, SyntaxTheme provider
  * @output Exports CodeBlock component and CodeBlockProps
  * @position Core implementation; read-only syntax-highlighted code display
  */
@@ -11,6 +11,7 @@
 import {
   useInsertionEffect,
   useEffect,
+  useId,
   useRef,
   useState,
   useCallback,
@@ -32,6 +33,7 @@ import {
   easeVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {Icon} from '../Icon';
 import {
   tokenize,
@@ -43,6 +45,7 @@ import type {SyntaxToken, TokenLine} from './tokenizer';
 import {ensureHighlightStyles} from './highlightStyles';
 import {applyHighlightRangesChunked} from './highlightRanges';
 import {themeProps} from '../utils/themeProps';
+import {SyntaxTheme, type SyntaxThemeDefinition} from '../theme/syntax';
 
 // ---------------------------------------------------------------------------
 // Styles
@@ -173,6 +176,17 @@ const styles = stylex.create({
   headerCollapsible: {
     cursor: 'pointer',
     userSelect: 'none',
+    // Restore a keyboard-only focus ring with the standard token/offset so this
+    // disclosure control matches the rest of the system (Collapsible, TabMenu);
+    // otherwise it falls back to the inconsistent UA default outline.
+    outline: {
+      default: null,
+      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+    },
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': '2px',
+    },
   },
   gutter: {
     flexShrink: 0,
@@ -382,6 +396,14 @@ export interface CodeBlockProps extends BaseProps<HTMLPreElement> {
     language: string,
   ) => {type: string; start: number; end: number}[];
   highlightMode?: 'auto' | 'ranges' | 'spans';
+  /**
+   * Per-instance syntax theme override. Shorthand for wrapping this block in
+   * `<SyntaxTheme theme={...}>` — accepts a preset from
+   * `@astryxdesign/core/theme/syntax` or a theme created with
+   * `defineSyntaxTheme()`. Without it, the block uses the theme-level syntax
+   * colors from the nearest SyntaxTheme ancestor or `defineTheme({ syntax })`.
+   */
+  syntaxTheme?: SyntaxThemeDefinition;
 }
 
 // ---------------------------------------------------------------------------
@@ -633,6 +655,7 @@ export function CodeBlock({
   container = 'card',
   tokenizer: customTokenizer,
   highlightMode = 'auto',
+  syntaxTheme,
   xstyle,
   className,
   style,
@@ -640,6 +663,17 @@ export function CodeBlock({
   ...props
 }: CodeBlockProps) {
   const [copied, setCopied] = useState(false);
+  const copyResetTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const announce = useAnnounce();
+
+  // Clear a pending "copied" reset when the block unmounts.
+  useEffect(() => {
+    return () => {
+      if (copyResetTimerRef.current != null) {
+        clearTimeout(copyResetTimerRef.current);
+      }
+    };
+  }, []);
 
   const useSpans =
     highlightMode === 'spans' ||
@@ -665,12 +699,23 @@ export function CodeBlock({
     try {
       await navigator.clipboard.writeText(code);
       setCopied(true);
+      // Swapping the button's aria-label alone isn't reliably announced by
+      // screen readers, so confirm the copy via a polite live region.
+      announce('Copied');
       onCopy?.();
-      setTimeout(() => setCopied(false), 2000);
+      // Restart the reset timer on every copy — otherwise a rapid re-copy
+      // is reverted early by the previous click's timer.
+      if (copyResetTimerRef.current != null) {
+        clearTimeout(copyResetTimerRef.current);
+      }
+      copyResetTimerRef.current = setTimeout(() => {
+        copyResetTimerRef.current = null;
+        setCopied(false);
+      }, 2000);
     } catch {
       // Clipboard failures leave the copied state unchanged.
     }
-  }, [code, onCopy]);
+  }, [code, onCopy, announce]);
 
   const sizeStyle = size === 'sm' ? styles.sizeSm : styles.sizeMd;
   const gutterSizeStyle = size === 'sm' ? styles.gutterSm : styles.gutterMd;
@@ -680,6 +725,11 @@ export function CodeBlock({
 
   const canCollapse = isCollapsible && lines.length >= collapsibleThreshold;
   const [isCollapsed, setIsCollapsed] = useState(false);
+  // Links the collapsible header to the code region it shows/hides so assistive
+  // tech can move from the button to its controlled content (disclosure
+  // pattern). The region stays mounted when collapsed (CSS grid animation), so
+  // this is always a resolvable reference — aria-controls can be unconditional.
+  const regionId = useId();
 
   const scrollContainerRef = useRef<HTMLDivElement>(null);
   const scrollStyle: CSSProperties | undefined = maxHeight
@@ -717,6 +767,7 @@ export function CodeBlock({
         role={canCollapse ? 'button' : undefined}
         tabIndex={canCollapse ? 0 : undefined}
         aria-expanded={canCollapse ? !isCollapsed : undefined}
+        aria-controls={canCollapse ? regionId : undefined}
         onClick={canCollapse ? () => setIsCollapsed(prev => !prev) : undefined}
         onKeyDown={
           canCollapse
@@ -802,7 +853,7 @@ export function CodeBlock({
     </div>
   );
 
-  return (
+  const block = (
     <pre
       ref={ref}
       {...mergeProps(
@@ -820,6 +871,7 @@ export function CodeBlock({
       {headerEl}
       {canCollapse ? (
         <div
+          id={regionId}
           {...stylex.props(
             styles.collapseGrid,
             isCollapsed && styles.collapseGridCollapsed,
@@ -832,6 +884,12 @@ export function CodeBlock({
       {!showHeader && copyButtonEl}
     </pre>
   );
+
+  return syntaxTheme ? (
+    <SyntaxTheme theme={syntaxTheme}>{block}</SyntaxTheme>
+  ) : (
+    block
+  );
 }
 
 CodeBlock.displayName = 'CodeBlock';

package/src/Collapsible/Collapsible.doc.mjs

@@ -16,7 +16,8 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-collapsible'},
+      {className: 'astryx-collapsible', visualProps: ['density']},
+      {className: 'astryx-collapsible-group', visualProps: ['density']},
     ],
   },
   description: 'A primitive that makes any content collapsible: a trigger button toggles visibility of the content area, managing its own state or deferring to a parent CollapsibleGroup.',
@@ -69,7 +70,8 @@ export const docs = {
   usage: {
     description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in CollapsibleGroup for accordion behavior. For custom collapsible components, use the `useCollapsible` hook directly (`astryx hook useCollapsible`).',
     bestPractices: [
-      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts.' },
+      { guidance: true, description: 'Use hasDividers on CollapsibleGroup for FAQ-style lists — built-in row hairlines with themed border tokens, no hand-rolled borders.' },
+      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts, or use CollapsibleGroup\'s hasDividers for flat lists; don\'t combine both.' },
       { guidance: true, description: 'Use CollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },
       { guidance: true, description: 'Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.' },
       { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view; don\'t make users click to see essential info.' },
@@ -90,7 +92,8 @@ export const docsZh = {
   usage: {
     description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in CollapsibleGroup for accordion behavior.',
     bestPractices: [
-      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts.' },
+      { guidance: true, description: 'Use hasDividers on CollapsibleGroup for FAQ-style lists — built-in row hairlines with themed border tokens, no hand-rolled borders.' },
+      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts, or use CollapsibleGroup\'s hasDividers for flat lists; don\'t combine both.' },
       { guidance: true, description: 'Use CollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },
       { guidance: true, description: 'Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.' },
       { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view; don\'t make users click to see essential info.' },
@@ -107,7 +110,8 @@ export const docsDense = {
   usage: {
     description: 'Collapsible hides and reveals content behind a trigger button. Use in settings, FAQs, or detail views. Wrap in CollapsibleGroup for accordion behavior.',
     bestPractices: [
-      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts.' },
+      { guidance: true, description: 'Use hasDividers on CollapsibleGroup for FAQ-style lists — built-in row hairlines, no hand-rolled borders.' },
+      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation, or use CollapsibleGroup\'s hasDividers for flat lists; not both.' },
       { guidance: true, description: 'Use CollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },
       { guidance: true, description: 'Use type="multiple" when users need to compare across sections.' },
       { guidance: true, description: 'Start sections open (defaultIsOpen) when content is needed on first view.' },