@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/Calendar/Calendar.tsx

@@ -57,7 +57,7 @@ import {
   DATE_FORMAT_WITH_WEEKDAY,
   DATE_FORMAT_MONTH_YEAR,
 } from '../utils/plainDate';
-import {mergeProps, composeEventHandlers} from '../utils';
+import {mergeProps, composeEventHandlers, rtlStyles} from '../utils';
 import {
   computeDayCellState,
   computeRangeRounding,
@@ -411,8 +411,16 @@ export function Calendar({ref, ...props}: CalendarProps) {
       } else {
         // Range mode
         if (rangeSelectionStart === null) {
-          // First click - start the range
+          // First click - start the range. Nothing else about this pick is
+          // perceivable non-visually (WCAG 1.3.1) — the grid doesn't move, so
+          // the month-change announcement stays silent — so speak the range
+          // progress through the same polite live region.
           setRangeSelectionStart(iso);
+          announce(
+            t('@astryx.calendar.rangeStartAnnounce', {
+              date: plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY),
+            }),
+          );
         } else {
           // Second click - complete the range
           const startPd = plainDateFromISO(rangeSelectionStart);
@@ -432,10 +440,24 @@ export function Calendar({ref, ...props}: CalendarProps) {
           setInternalValue(range);
           setRangeSelectionStart(null);
           (onChange as CalendarRangeProps['onChange'])?.(range);
+          // Completed-range announcement, in chronological order (matches the
+          // swapped {start, end} above even for a reverse pick).
+          announce(
+            t('@astryx.calendar.rangeCompleteAnnounce', {
+              start: plainDateFormat(
+                plainDateFromISO(start),
+                DATE_FORMAT_WITH_WEEKDAY,
+              ),
+              end: plainDateFormat(
+                plainDateFromISO(end),
+                DATE_FORMAT_WITH_WEEKDAY,
+              ),
+            }),
+          );
         }
       }
     },
-    [mode, onChange, rangeSelectionStart],
+    [mode, onChange, rangeSelectionStart, announce, t],
   );
 
   return (
@@ -452,13 +474,17 @@ export function Calendar({ref, ...props}: CalendarProps) {
       {/* Header with navigation */}
       <div {...stylex.props(calendarStyles.header)}>
         <Button
+          {...themeProps('calendar-nav', {
+            nav: 'prev',
+            disabled: !canNavigatePrevious ? 'disabled' : null,
+          })}
           label={t('@astryx.calendar.previousMonth')}
           variant="ghost"
           icon={
             // Wrapper span (not Icon props): Icon's string mode clobbers
             // caller classNames, so the RTL mirror must live on its own
             // element.
-            <span {...stylex.props(calendarStyles.navIcon)}>
+            <span {...stylex.props(calendarStyles.navIcon, rtlStyles.mirror)}>
               <Icon icon="chevronLeft" size="sm" color="inherit" />
             </span>
           }
@@ -472,10 +498,14 @@ export function Calendar({ref, ...props}: CalendarProps) {
         </span>
 
         <Button
+          {...themeProps('calendar-nav', {
+            nav: 'next',
+            disabled: !canNavigateNext ? 'disabled' : null,
+          })}
           label={t('@astryx.calendar.nextMonth')}
           variant="ghost"
           icon={
-            <span {...stylex.props(calendarStyles.navIcon)}>
+            <span {...stylex.props(calendarStyles.navIcon, rtlStyles.mirror)}>
               <Icon icon="chevronRight" size="sm" color="inherit" />
             </span>
           }
@@ -782,6 +812,9 @@ function MonthGrid({
         ref={gridRef}
         role="grid"
         aria-label={monthLabel}
+        // APG grid pattern: a range selection holds multiple selected cells,
+        // so the grid must advertise multi-selectability.
+        aria-multiselectable={mode === 'range' ? true : undefined}
         onKeyDown={handleGridKeyDown}
         onFocus={handleGridFocus}
         {...stylex.props(
@@ -856,6 +889,7 @@ function MonthGrid({
                     isDisabled={isDateDisabled(day.date)}
                     neighbors={neighbors}
                     isTabbable={day.iso === seedTabbableIso}
+                    isRangeSelectionInProgress={rangeSelectionStart !== null}
                     onDayClick={onDayClick}
                     onDayHover={onDayHover}
                   />
@@ -897,6 +931,13 @@ interface DayCellProps {
    * existing `tabindex="0"` and repairs/moves it on navigation and focus.
    */
   isTabbable: boolean;
+  /**
+   * Whether a range selection is mid-flight (first pick made, awaiting the
+   * second). Disambiguates the accessible name of the picked day: mid-flight
+   * it is only the "range start", while a completed one-day range is both
+   * "range start and range end" (rangeStart === rangeEnd in both cases).
+   */
+  isRangeSelectionInProgress: boolean;
   onDayClick: (date: PlainDate) => void;
   onDayHover: (date: PlainDate | null) => void;
 }
@@ -915,9 +956,11 @@ function DayCell({
   isDisabled,
   neighbors,
   isTabbable: isTabbableDay,
+  isRangeSelectionInProgress,
   onDayClick,
   onDayHover,
 }: DayCellProps) {
+  const t = useTranslator();
   const {date, isOutside, dayNumber} = day;
 
   if (isOutside && !hasOutsideDays) {
@@ -941,6 +984,43 @@ function DayCell({
   });
 
   const endpoint = isEndpoint(state);
+
+  // The day's focus-ring treatment, derived once so the reflected `marker`
+  // theme state and the StyleX ring styles below share a single source of
+  // truth. `state.isSelected` is single-select only, so a range endpoint that
+  // is today still qualifies for the today-in-range ring (unchanged prior
+  // behavior).
+  const showsTodayRing = state.isToday && !state.isSelected && !state.isInRange;
+  const showsTodayInRangeRing =
+    state.isToday && !state.isSelected && state.isInRange;
+  const markerState: 'today-only' | 'today-in-range' | null = showsTodayRing
+    ? 'today-only'
+    : showsTodayInRangeRing
+      ? 'today-in-range'
+      : null;
+
+  // Accessible name for the day button. Roving focus lands on the <button>,
+  // not the role="gridcell" wrapper that carries aria-selected — and
+  // aria-selected is invalid on role="button" — so the selection/range state
+  // must be encoded into the button's name (WCAG 4.1.2). Localized via ICU
+  // params rather than string concatenation. A mid-flight first pick (where
+  // rangeStart === rangeEnd) reads as "range start" only; a completed one-day
+  // range reads as both start and end.
+  const dateLabel = plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY);
+  const dayLabel = state.isSelected
+    ? t('@astryx.calendar.daySelected', {date: dateLabel})
+    : state.isRangeStart && state.isRangeEnd
+      ? isRangeSelectionInProgress
+        ? t('@astryx.calendar.dayRangeStart', {date: dateLabel})
+        : t('@astryx.calendar.dayRangeStartAndEnd', {date: dateLabel})
+      : state.isRangeStart
+        ? t('@astryx.calendar.dayRangeStart', {date: dateLabel})
+        : state.isRangeEnd
+          ? t('@astryx.calendar.dayRangeEnd', {date: dateLabel})
+          : state.isInRange
+            ? t('@astryx.calendar.dayInRange', {date: dateLabel})
+            : dateLabel;
+
   const rangeRounding = computeRangeRounding(state, {
     prevInRange: neighbors.prevInRange,
     nextInRange: neighbors.nextInRange,
@@ -961,16 +1041,16 @@ function DayCell({
           {...stylex.props(
             dayCellStyles.rangeBg,
             dayCellTheme.rangeBg,
-            rangeRounding.roundLeft && dayCellStyles.rangeBgRadiusLeft,
-            rangeRounding.roundRight && dayCellStyles.rangeBgRadiusRight,
-            state.isRangeStart && dayCellStyles.rangeInsetLeft,
+            rangeRounding.roundStart && dayCellStyles.rangeBgRadiusStart,
+            rangeRounding.roundEnd && dayCellStyles.rangeBgRadiusEnd,
+            state.isRangeStart && dayCellStyles.rangeInsetStart,
             state.isRangeStart &&
-              rangeRounding.roundRight &&
-              dayCellStyles.rangeInsetRight,
-            state.isRangeEnd && dayCellStyles.rangeInsetRight,
+              rangeRounding.roundEnd &&
+              dayCellStyles.rangeInsetEnd,
+            state.isRangeEnd && dayCellStyles.rangeInsetEnd,
             state.isRangeStart &&
-              rangeRounding.roundLeft &&
-              dayCellStyles.rangeInsetLeft,
+              rangeRounding.roundStart &&
+              dayCellStyles.rangeInsetStart,
           )}
         />
       )}
@@ -981,8 +1061,8 @@ function DayCell({
           {...stylex.props(
             dayCellStyles.previewBg,
             dayCellTheme.previewBg,
-            previewRounding.roundLeft && dayCellStyles.previewBgRadiusLeft,
-            previewRounding.roundRight && dayCellStyles.previewBgRadiusRight,
+            previewRounding.roundStart && dayCellStyles.previewBgRadiusStart,
+            previewRounding.roundEnd && dayCellStyles.previewBgRadiusEnd,
             state.isPreviewStart && dayCellStyles.previewStart,
             state.isPreviewEnd && dayCellStyles.previewEnd,
           )}
@@ -993,7 +1073,7 @@ function DayCell({
       <button
         type="button"
         data-date={day.iso}
-        aria-label={plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY)}
+        aria-label={dayLabel}
         aria-disabled={state.effectivelyDisabled || undefined}
         // Mark today's cell programmatically (APG date-picker pattern), not just
         // visually, so screen-reader users can identify the current date.
@@ -1010,28 +1090,27 @@ function DayCell({
             today: state.isToday ? 'today' : null,
             disabled: state.effectivelyDisabled ? 'disabled' : null,
             'in-range': state.isInRange ? 'in-range' : null,
+            // `marker` reflects the day's *actual* focus-ring treatment as a
+            // single compound state, so a theme can target exactly the states
+            // the ring is drawn under without needing `:not()` in the theme
+            // key. It is null unless a ring is shown:
+            //   'today-only'     → today, not single-selected, not in a range
+            //   'today-in-range' → today, not single-selected, inside a range
+            // `isSelected` here is single-select only (see computeDayCellState),
+            // so a today range endpoint still shows the today-in-range ring —
+            // `marker` mirrors the StyleX conditions below exactly, preserving
+            // the default rendering.
+            marker: markerState,
           }),
           stylex.props(
             dayCellStyles.day,
             dayCellTheme.day,
             isOutside && dayCellStyles.dayOutside,
             isOutside && dayCellTheme.dayOutside,
-            state.isToday &&
-              !state.isSelected &&
-              !state.isInRange &&
-              dayCellStyles.dayToday,
-            state.isToday &&
-              !state.isSelected &&
-              !state.isInRange &&
-              dayCellTheme.dayToday,
-            state.isToday &&
-              !state.isSelected &&
-              state.isInRange &&
-              dayCellStyles.dayTodayInRange,
-            state.isToday &&
-              !state.isSelected &&
-              state.isInRange &&
-              dayCellTheme.dayTodayInRange,
+            showsTodayRing && dayCellStyles.dayToday,
+            showsTodayRing && dayCellTheme.dayToday,
+            showsTodayInRangeRing && dayCellStyles.dayTodayInRange,
+            showsTodayInRangeRing && dayCellTheme.dayTodayInRange,
             endpoint && dayCellStyles.daySelected,
             endpoint && dayCellTheme.daySelected,
             state.effectivelyDisabled && dayCellStyles.dayDisabled,

package/src/Calendar/dayCellUtils.test.ts

@@ -45,6 +45,11 @@ describe('computeDayCellState', () => {
     expect(state.isToday).toBe(false);
   });
 
+  it('does not identify an outside day as today', () => {
+    const state = computeDayCellState(makeInput({isOutside: true}));
+    expect(state.isToday).toBe(false);
+  });
+
   it('identifies selected day in single mode', () => {
     const state = computeDayCellState(
       makeInput({selectedDate: plainDateFromISO('2024-03-15')}),
@@ -176,8 +181,8 @@ describe('computeRangeRounding', () => {
       }),
     );
     const rounding = computeRangeRounding(state);
-    expect(rounding.roundLeft).toBe(true);
-    expect(rounding.roundRight).toBe(false);
+    expect(rounding.roundStart).toBe(true);
+    expect(rounding.roundEnd).toBe(false);
   });
 
   it('rounds left at first column even without range start', () => {
@@ -191,7 +196,7 @@ describe('computeRangeRounding', () => {
       }),
     );
     const rounding = computeRangeRounding(state);
-    expect(rounding.roundLeft).toBe(true);
+    expect(rounding.roundStart).toBe(true);
   });
 
   it('rounds right at last column', () => {
@@ -205,7 +210,7 @@ describe('computeRangeRounding', () => {
       }),
     );
     const rounding = computeRangeRounding(state);
-    expect(rounding.roundRight).toBe(true);
+    expect(rounding.roundEnd).toBe(true);
   });
 
   // #2715 follow-up: cap the highlight where the range meets a disabled or
@@ -225,8 +230,8 @@ describe('computeRangeRounding', () => {
       prevInRange: true,
       nextInRange: false,
     });
-    expect(rounding.roundLeft).toBe(false);
-    expect(rounding.roundRight).toBe(true);
+    expect(rounding.roundStart).toBe(false);
+    expect(rounding.roundEnd).toBe(true);
   });
 
   it('caps the left edge when the previous day breaks the range', () => {
@@ -243,8 +248,8 @@ describe('computeRangeRounding', () => {
       prevInRange: false,
       nextInRange: true,
     });
-    expect(rounding.roundLeft).toBe(true);
-    expect(rounding.roundRight).toBe(false);
+    expect(rounding.roundStart).toBe(true);
+    expect(rounding.roundEnd).toBe(false);
   });
 
   it('does not cap a mid-range day when both neighbours continue the range', () => {
@@ -261,8 +266,8 @@ describe('computeRangeRounding', () => {
       prevInRange: true,
       nextInRange: true,
     });
-    expect(rounding.roundLeft).toBe(false);
-    expect(rounding.roundRight).toBe(false);
+    expect(rounding.roundStart).toBe(false);
+    expect(rounding.roundEnd).toBe(false);
   });
 });
 
@@ -308,8 +313,8 @@ describe('computePreviewRounding', () => {
       }),
     );
     const rounding = computePreviewRounding(state);
-    expect(rounding.roundLeft).toBe(true);
-    expect(rounding.roundRight).toBe(false);
+    expect(rounding.roundStart).toBe(true);
+    expect(rounding.roundEnd).toBe(false);
   });
 
   // #2715: the hover preview needs the same disabled/outside caps as the
@@ -327,8 +332,8 @@ describe('computePreviewRounding', () => {
       prevInPreview: true,
       nextInPreview: false,
     });
-    expect(rounding.roundLeft).toBe(false);
-    expect(rounding.roundRight).toBe(true);
+    expect(rounding.roundStart).toBe(false);
+    expect(rounding.roundEnd).toBe(true);
   });
 
   it('caps the left edge when the previous day breaks the preview run', () => {
@@ -344,8 +349,8 @@ describe('computePreviewRounding', () => {
       prevInPreview: false,
       nextInPreview: true,
     });
-    expect(rounding.roundLeft).toBe(true);
-    expect(rounding.roundRight).toBe(false);
+    expect(rounding.roundStart).toBe(true);
+    expect(rounding.roundEnd).toBe(false);
   });
 
   it('does not cap a mid-preview day when both neighbours continue', () => {
@@ -361,8 +366,8 @@ describe('computePreviewRounding', () => {
       prevInPreview: true,
       nextInPreview: true,
     });
-    expect(rounding.roundLeft).toBe(false);
-    expect(rounding.roundRight).toBe(false);
+    expect(rounding.roundStart).toBe(false);
+    expect(rounding.roundEnd).toBe(false);
   });
 });
 

package/src/Calendar/dayCellUtils.ts

@@ -56,7 +56,7 @@ export function computeDayCellState(input: DayCellStateInput): DayCellState {
 
   return {
     effectivelyDisabled: isDisabled || isOutside,
-    isToday: plainDateIsEqual(date, today),
+    isToday: !isOutside && plainDateIsEqual(date, today),
     isSelected: !!(
       !isOutside &&
       mode === 'single' &&
@@ -123,8 +123,8 @@ function computeHighlightRounding(input: {
   const nextBreaks =
     input.nextContinues !== undefined ? !input.nextContinues : false;
   return {
-    roundLeft: input.isStart || input.isFirstColumn || prevBreaks,
-    roundRight: input.isEnd || input.isLastColumn || nextBreaks,
+    roundStart: input.isStart || input.isFirstColumn || prevBreaks,
+    roundEnd: input.isEnd || input.isLastColumn || nextBreaks,
   };
 }
 

package/src/Calendar/styles.ts

@@ -65,18 +65,12 @@ export const calendarStyles = stylex.create({
     borderWidth: 0,
   },
   /**
-   * Wrapper for the month nav chevrons. In RTL the flex header already
-   * swaps the buttons' visual sides; the glyphs must mirror with them so
-   * "Previous month" points outward (visually right) instead of inward.
-   * Keyed on the dir attribute (dir="rtl"), same as MobileNav's drawer
-   * transform — bare CSS `direction: rtl` alone won't trigger it.
+   * Wrapper for the month nav chevrons. RTL mirroring is applied by
+   * composing the shared `rtlStyles.mirror` transform onto this wrapper
+   * at the call site (see Calendar.tsx).
    */
   navIcon: {
     display: 'inline-flex',
-    transform: {
-      default: null,
-      ':is([dir="rtl"] *)': 'scaleX(-1)',
-    },
   },
 });
 
@@ -145,24 +139,24 @@ export const dayCellStyles = stylex.create({
     position: 'absolute',
     top: '2px',
     bottom: '2px',
-    left: 0,
-    right: 0,
+    insetInlineStart: 0,
+    insetInlineEnd: 0,
   },
-  rangeBgRadiusLeft: {
-    left: '2px',
-    borderTopLeftRadius: radiusVars['--radius-full'],
-    borderBottomLeftRadius: radiusVars['--radius-full'],
+  rangeBgRadiusStart: {
+    insetInlineStart: '2px',
+    borderStartStartRadius: radiusVars['--radius-full'],
+    borderEndStartRadius: radiusVars['--radius-full'],
   },
-  rangeBgRadiusRight: {
-    right: '2px',
-    borderTopRightRadius: radiusVars['--radius-full'],
-    borderBottomRightRadius: radiusVars['--radius-full'],
+  rangeBgRadiusEnd: {
+    insetInlineEnd: '2px',
+    borderStartEndRadius: radiusVars['--radius-full'],
+    borderEndEndRadius: radiusVars['--radius-full'],
   },
-  rangeInsetLeft: {
-    left: '2px',
+  rangeInsetStart: {
+    insetInlineStart: '2px',
   },
-  rangeInsetRight: {
-    right: '2px',
+  rangeInsetEnd: {
+    insetInlineEnd: '2px',
   },
 
   // Preview background - structural positioning
@@ -170,28 +164,28 @@ export const dayCellStyles = stylex.create({
     position: 'absolute',
     top: '2px',
     bottom: '2px',
-    left: 0,
-    right: 0,
+    insetInlineStart: 0,
+    insetInlineEnd: 0,
   },
-  previewBgRadiusLeft: {
-    left: '2px',
-    borderTopLeftRadius: radiusVars['--radius-full'],
-    borderBottomLeftRadius: radiusVars['--radius-full'],
+  previewBgRadiusStart: {
+    insetInlineStart: '2px',
+    borderStartStartRadius: radiusVars['--radius-full'],
+    borderEndStartRadius: radiusVars['--radius-full'],
   },
-  previewBgRadiusRight: {
-    right: '2px',
-    borderTopRightRadius: radiusVars['--radius-full'],
-    borderBottomRightRadius: radiusVars['--radius-full'],
+  previewBgRadiusEnd: {
+    insetInlineEnd: '2px',
+    borderStartEndRadius: radiusVars['--radius-full'],
+    borderEndEndRadius: radiusVars['--radius-full'],
   },
   previewStart: {
-    left: '2px',
-    borderTopLeftRadius: radiusVars['--radius-full'],
-    borderBottomLeftRadius: radiusVars['--radius-full'],
+    insetInlineStart: '2px',
+    borderStartStartRadius: radiusVars['--radius-full'],
+    borderEndStartRadius: radiusVars['--radius-full'],
   },
   previewEnd: {
-    right: '2px',
-    borderTopRightRadius: radiusVars['--radius-full'],
-    borderBottomRightRadius: radiusVars['--radius-full'],
+    insetInlineEnd: '2px',
+    borderStartEndRadius: radiusVars['--radius-full'],
+    borderEndEndRadius: radiusVars['--radius-full'],
   },
 
   // Day button - structural

package/src/Card/Card.doc.mjs

@@ -67,6 +67,13 @@ export const docs = {
         'Background color variant. `default` uses the standard card background. `transparent` drops the background entirely. `muted` uses the muted background for de-emphasised cards. The non-semantic variants use the corresponding `--color-background-<name>` token.',
       default: "'default'",
     },
+    {
+      name: 'elevation',
+      type: "'none' | 'low' | 'med' | 'high'",
+      description:
+        'Resting shadow depth. `none` is flat; `low`/`med`/`high` map to the shadow token scale. Raise a card only when it needs to float above surrounding content.',
+      default: "'none'",
+    },
   ],
   playground: {
     defaults: {
@@ -127,6 +134,7 @@ export const docsZh = {
     {name: 'minHeight', type: 'SizeValue', description: '卡片最小高度。'},
     {name: 'children', type: 'ReactNode', description: '在卡片内部渲染的内容。'},
     {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: '使用间距比例的内边距。', default: '4'},
+    {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。`none` 为扁平；`low`/`med`/`high` 对应阴影令牌比例。', default: "'none'"},
   ],
   theming: {
     container: true,
@@ -170,5 +178,6 @@ export const docsDense = {
     children: 'content inside card',
     padding: 'internal padding via spacing scale',
     variant: 'background color variant; `default` = standard card bg, `transparent` = no background at all, `muted` = muted bg for de-emphasised cards; non-semantic variants use the corresponding `--color-background-<name>` token',
+    elevation: 'resting shadow depth: none (flat) | low | med | high (shadow token scale). Raise only to float above content.',
   },
 };

package/src/Card/Card.test.tsx

@@ -17,11 +17,29 @@ describe('Card', () => {
   });
 
   it('renders transparent variant with variant class', () => {
-    const {container} = render(
-      <Card variant="transparent">Content</Card>,
-    );
+    const {container} = render(<Card variant="transparent">Content</Card>);
     const root = container.firstElementChild!;
     expect(root.className).toContain('astryx-card');
     expect(root.className).toContain('transparent');
   });
+
+  it('applies a distinct class for each elevation level', () => {
+    const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+      const {container} = render(<Card elevation={elevation}>C</Card>);
+      return container.firstElementChild!.className;
+    };
+    const none = classFor('none');
+    const low = classFor('low');
+    const med = classFor('med');
+    const high = classFor('high');
+    expect(new Set([none, low, med, high]).size).toBe(4);
+  });
+
+  it('defaults to flat (elevation none) — same class as explicit none', () => {
+    const {container: defaultContainer} = render(<Card>C</Card>);
+    const {container: noneContainer} = render(<Card elevation="none">C</Card>);
+    expect(defaultContainer.firstElementChild!.className).toBe(
+      noneContainer.firstElementChild!.className,
+    );
+  });
 });

package/src/Card/Card.tsx

@@ -17,7 +17,12 @@
 
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {borderVars, colorVars, radiusVars} from '../theme/tokens.stylex';
+import {
+  borderVars,
+  colorVars,
+  radiusVars,
+  shadowVars,
+} from '../theme/tokens.stylex';
 import {container} from '../Layout/container.stylex';
 import type {SpacingToken} from '../Layout/container.stylex';
 import {
@@ -27,7 +32,7 @@ import {
   containerPaddingBlockEndVarStyles,
   spacingStepToToken,
 } from '../Layout/padding.stylex';
-import type {SizeValue, SpacingStep} from '../utils/types';
+import type {Elevation, SizeValue, SpacingStep} from '../utils/types';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -73,6 +78,13 @@ const styles = stylex.create({
     '--_card-radius': radiusVars['--radius-container'],
     borderRadius: 'var(--_card-radius)',
     overflow: 'clip',
+    // Resting elevation is set via --_card-elevation (see elevationStyles).
+    // The shadow list also reads --_card-ring so composing surfaces — e.g.
+    // SelectableCard's inset selection ring — can layer their own shadow
+    // alongside elevation instead of clobbering the single box-shadow property.
+    // Unset vars fall back to a transparent no-op shadow.
+    boxShadow:
+      'var(--_card-ring, 0 0 transparent), var(--_card-elevation, 0 0 transparent)',
   },
   // The border is drawn *inside* the padding — its width is subtracted from
   // each side — so total inset (border + padding) equals the padding token
@@ -135,6 +147,18 @@ const variantStyles = stylex.create({
   },
 });
 
+// Elevation → shadow-token map. Sets the private --_card-elevation variable
+// (not box-shadow directly) so it composes with --_card-ring in the shadow
+// list above — a selection ring and a resting elevation coexist without one
+// overwriting the other. 'none' is a transparent no-op (not the CSS literal
+// `none`, which would be invalid inside the comma-separated shadow list).
+const elevationStyles = stylex.create({
+  none: {'--_card-elevation': '0 0 transparent'},
+  low: {'--_card-elevation': shadowVars['--shadow-low']},
+  med: {'--_card-elevation': shadowVars['--shadow-med']},
+  high: {'--_card-elevation': shadowVars['--shadow-high']},
+});
+
 // Dynamic styles for sizing props
 const dynamicStyles = stylex.create({
   sizing: (
@@ -208,6 +232,13 @@ export interface CardProps extends BaseProps<HTMLDivElement> {
    * @default 'default'
    */
   variant?: CardVariant;
+
+  /**
+   * Resting elevation — the shadow depth the card sits at.
+   * `none` is flat; `low`/`med`/`high` map to the shadow token scale.
+   * @default 'none'
+   */
+  elevation?: Elevation;
 }
 
 /**
@@ -252,6 +283,7 @@ export function Card({
   children,
   padding,
   variant = 'default',
+  elevation = 'none',
   xstyle,
   className,
   style,
@@ -274,6 +306,7 @@ export function Card({
         stylex.props(
           styles.card,
           variantStyles[variant],
+          elevationStyles[elevation],
           hasFixedHeight && styles.scrollable,
           dynamicStyles.sizing(
             width ?? null,

package/src/Carousel/Carousel.doc.mjs

@@ -91,6 +91,7 @@ export const docsDense = {
       {guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge: gallery, product list.'},
       {guidance: true, description: 'Always provide an aria-label describing what the carousel contains: "Featured products", "Team members".'},
       {guidance: true, description: 'Use consistent gap + item width so the carousel looks intentional, not like content overflowing by accident.'},
+      {guidance: true, description: 'Trust built-in navigation: trackpad users swipe horizontally, mouse users hold Shift + wheel to move through items.'},
       {guidance: false, description: 'Use a carousel for content every user must see. Not everyone scrolls horizontally, so put critical content above the fold.'},
       {guidance: false, description: 'Auto-advance items. Let the user scroll at their own pace.'},
       {guidance: false, description: 'Nest carousels. A carousel inside a carousel is confusing and breaks keyboard navigation.'},