@astryxdesign/core 0.4.7 → 0.5.0-canary.055e75f

package/src/Calendar/Calendar.test.tsx

@@ -13,6 +13,10 @@ import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {act, render, screen, within, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {getButton} from '../__tests__/fastRoleQueries';
+import {
+  getForcedColorsRules,
+  getAllInjectedCss,
+} from '../__tests__/forcedColors';
 import * as stylex from '@stylexjs/stylex';
 import {Calendar} from './Calendar';
 import type {CalendarHandle} from './Calendar';
@@ -263,6 +267,58 @@ describe('Calendar', () => {
     expect(day15).not.toBeDisabled();
   });
 
+  // ─── Initial Visible Month ───────────────────────────────────
+
+  describe('opens on a month inside the min/max window', () => {
+    beforeEach(() => {
+      vi.useFakeTimers({toFake: ['Date']});
+      vi.setSystemTime(new Date(2026, 7, 21, 12, 0, 0));
+    });
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('opens on today when today is inside the window', () => {
+      render(<Calendar min="2026-01-01" max="2026-12-31" />);
+
+      expect(screen.getByText('August 2026')).toBeInTheDocument();
+    });
+
+    it('opens on min when the window is entirely in the future', () => {
+      render(<Calendar min="2027-03-04" max="2027-06-30" />);
+
+      expect(screen.getByText('March 2027')).toBeInTheDocument();
+      expect(getDayButton(4, 'March', 2027)).not.toBeDisabled();
+    });
+
+    it('opens on max when the window is entirely in the past', () => {
+      render(<Calendar min="2019-01-01" max="2019-04-30" />);
+
+      expect(screen.getByText('April 2019')).toBeInTheDocument();
+      expect(getDayButton(30, 'April', 2019)).not.toBeDisabled();
+    });
+
+    it('keeps max in the last pane in the two-month layout', () => {
+      render(<Calendar numberOfMonths={2} min="2019-01-01" max="2019-04-30" />);
+
+      expect(screen.getByText('March 2019 – April 2019')).toBeInTheDocument();
+    });
+
+    it('still honors an explicit focusDate outside the window', () => {
+      render(
+        <Calendar focusDate="2026-01-01" min="2027-03-04" max="2027-06-30" />,
+      );
+
+      expect(screen.getByText('January 2026')).toBeInTheDocument();
+    });
+
+    it('still opens on the selected value outside the window', () => {
+      render(<Calendar defaultValue="2031-07-04" min="2019-01-01" />);
+
+      expect(screen.getByText('July 2031')).toBeInTheDocument();
+    });
+  });
+
   it('respects custom dateConstraints', () => {
     // Only allow weekdays
     const isWeekday = (date: Date) => {
@@ -337,6 +393,33 @@ describe('Calendar', () => {
     expect(getDayButton(9)).not.toBeDisabled();
   });
 
+  it('announces the cleared range in the provider locale', async () => {
+    const user = userEvent.setup();
+
+    render(
+      <InternationalizationProvider locale="ja-JP">
+        <Calendar mode="range" focusDate="2026-01-01" />
+      </InternationalizationProvider>,
+    );
+
+    // The day button's own accessible name is already localized through the
+    // provider. The announcement has to use the same date string: formatting
+    // it without the locale silently falls back to the host locale, so a
+    // Japanese user hears an English date.
+    const anchor = document.querySelector<HTMLButtonElement>(
+      'button[data-date="2026-01-10"]',
+    );
+    const localizedDate = anchor?.getAttribute('aria-label');
+    expect(localizedDate).toBeTruthy();
+
+    await user.click(anchor as HTMLButtonElement);
+    await user.click(anchor as HTMLButtonElement);
+
+    await waitFor(() => {
+      expect(politeRegion()?.textContent).toContain(localizedDate);
+    });
+  });
+
   it('does not apply range-span constraints in single mode', async () => {
     const user = userEvent.setup();
 
@@ -1378,3 +1461,23 @@ describe('Calendar', () => {
     });
   });
 });
+
+// jsdom cannot emulate forced-colors rendering, so this asserts that the
+// compiled output includes the forced-colors rules; visual behavior needs
+// manual verification under Windows High Contrast.
+describe('forced colors (WCAG 1.4.11)', () => {
+  it('compiles a forced-colors fill so the selected date survives Windows High Contrast', () => {
+    render(
+      <Calendar mode="single" value="2026-01-15" focusDate="2026-01-01" />,
+    );
+
+    const css = getForcedColorsRules();
+    // Without these the accent fill is stripped and the selected date renders
+    // identically to every other day in the month.
+    expect(css).toContain('background-color: highlight;');
+    expect(css).toContain('color: highlighttext;');
+    // A <button> keeps the native ButtonFace surface and ignores the authored
+    // Highlight fill unless it opts out of UA remapping.
+    expect(getAllInjectedCss()).toContain('forced-color-adjust: none;');
+  });
+});

package/src/Calendar/Calendar.tsx

@@ -11,6 +11,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Calendar/Calendar.doc.mjs (props table, features, implementation notes)
+ * - /packages/core/src/Calendar/getInitialFocusDate.ts (which month the calendar opens on)
  * - /packages/core/src/Calendar/Calendar.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Calendar/index.ts (exports if types change)
  * - /apps/storybook/stories/Calendar.stories.tsx (storybook stories)
@@ -60,6 +61,7 @@ import {
 } from '../utils/plainDate';
 import {mergeProps, composeEventHandlers, rtlStyles} from '../utils';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {getInitialFocusDate} from './getInitialFocusDate';
 import {
   computeDayCellState,
   computeRangeRounding,
@@ -142,7 +144,9 @@ interface CalendarBaseProps extends Omit<
 
   /**
    * Controlled focus date (which month is visible).
-   * If not provided, defaults to selected date or today.
+   * If not provided, defaults to the selected date, else today clamped into
+   * the `min`/`max` window (so a window that excludes today opens on the
+   * bound nearest to it, not on an all-disabled month).
    */
   focusDate?: ISODateString;
 
@@ -277,20 +281,19 @@ export function Calendar({ref, ...props}: CalendarProps) {
   // Determine effective value
   const effectiveValue = value !== undefined ? value : internalValue;
 
-  // Focus date state (which month is visible)
-  const [internalFocusDate, setInternalFocusDate] = useState<PlainDate>(() => {
-    if (focusDateProp) {
-      return plainDateFromISO(focusDateProp);
-    }
-    if (effectiveValue) {
-      if (typeof effectiveValue === 'string') {
-        return plainDateFromISO(effectiveValue);
-      } else {
-        return plainDateFromISO(effectiveValue.start);
-      }
-    }
-    return plainDateToday();
-  });
+  // Focus date state (which month is visible). Falls back to today, clamped
+  // into the min/max window so a window that doesn't contain today doesn't
+  // open on an all-disabled month.
+  const [internalFocusDate, setInternalFocusDate] = useState<PlainDate>(() =>
+    getInitialFocusDate({
+      focusDate: focusDateProp,
+      value: effectiveValue,
+      min,
+      max,
+      numberOfMonths,
+      today,
+    }),
+  );
 
   // Use controlled focusDate if callback is provided, otherwise use internal state
   const isControlledFocus =
@@ -459,7 +462,7 @@ export function Calendar({ref, ...props}: CalendarProps) {
             setRangeSelectionStart(null);
             announce(
               t('@astryx.calendar.rangeClearedAnnounce', {
-                date: plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY),
+                date: plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY, locale),
               }),
             );
             return;

package/src/Calendar/getInitialFocusDate.test.ts

@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getInitialFocusDate.test.ts
+ * @input Uses vitest
+ * @output Test suite for getInitialFocusDate
+ * @position Tests for getInitialFocusDate.ts
+ *
+ * SYNC: When getInitialFocusDate.ts changes, update tests accordingly
+ */
+
+import {describe, it, expect} from 'vitest';
+import {getInitialFocusDate} from './getInitialFocusDate';
+import {plainDateFromISO, plainDateToISO} from '../utils/plainDate';
+
+const TODAY = plainDateFromISO('2026-08-21');
+
+function focusISO(options: Partial<Parameters<typeof getInitialFocusDate>[0]>) {
+  return plainDateToISO(
+    getInitialFocusDate({numberOfMonths: 1, today: TODAY, ...options}),
+  );
+}
+
+describe('getInitialFocusDate', () => {
+  it('opens on today when there are no bounds', () => {
+    expect(focusISO({})).toBe('2026-08-21');
+  });
+
+  it('opens on today when today is inside the min/max window', () => {
+    expect(focusISO({min: '2026-01-01', max: '2026-12-31'})).toBe('2026-08-21');
+  });
+
+  it('treats the bounds as inclusive', () => {
+    expect(focusISO({min: '2026-08-21'})).toBe('2026-08-21');
+    expect(focusISO({max: '2026-08-21'})).toBe('2026-08-21');
+  });
+
+  it('opens on min when the whole window is in the future', () => {
+    expect(focusISO({min: '2027-03-04', max: '2027-06-30'})).toBe('2027-03-04');
+  });
+
+  it('opens on max when the whole window is in the past', () => {
+    expect(focusISO({min: '2019-01-01', max: '2019-04-30'})).toBe('2019-04-01');
+  });
+
+  it('clamps against a one-sided min', () => {
+    expect(focusISO({min: '2030-05-17'})).toBe('2030-05-17');
+  });
+
+  it('clamps against a one-sided max', () => {
+    expect(focusISO({max: '2020-02-09'})).toBe('2020-02-01');
+  });
+
+  it('lands max in the last pane in the two-month layout', () => {
+    // Opening on max's month would spend the second pane entirely
+    // out of bounds, so the window's end sits on the right instead.
+    expect(focusISO({max: '2020-02-09', numberOfMonths: 2})).toBe('2020-01-01');
+  });
+
+  it('does not shift the two-month layout back past min', () => {
+    expect(
+      focusISO({min: '2020-02-03', max: '2020-02-09', numberOfMonths: 2}),
+    ).toBe('2020-02-03');
+  });
+
+  it('prefers the selected value over the bounds', () => {
+    expect(focusISO({value: '2031-07-04', min: '2019-01-01'})).toBe(
+      '2031-07-04',
+    );
+  });
+
+  it('uses a range value start as the visible month', () => {
+    expect(focusISO({value: {start: '2019-03-08', end: '2019-03-19'}})).toBe(
+      '2019-03-08',
+    );
+  });
+
+  it('prefers an explicit focusDate over everything else', () => {
+    expect(
+      focusISO({
+        focusDate: '2015-11-02',
+        value: '2031-07-04',
+        min: '2026-01-01',
+        max: '2026-12-31',
+      }),
+    ).toBe('2015-11-02');
+  });
+
+  it('prefers min when the bounds are inverted', () => {
+    // Degenerate input (min after max) — resolve it deterministically
+    // rather than reading the second bound off a contradiction.
+    expect(focusISO({min: '2027-01-01', max: '2020-01-01'})).toBe('2027-01-01');
+  });
+});

package/src/Calendar/getInitialFocusDate.ts

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getInitialFocusDate.ts
+ * @input PlainDate utilities, min/max bounds, today
+ * @output Exports getInitialFocusDate — the month Calendar opens on
+ * @position Calendar-specific helper; used by Calendar.tsx
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Calendar/getInitialFocusDate.test.ts
+ * - /packages/core/src/Calendar/Calendar.tsx (the only caller)
+ */
+
+import type {ISODateString, DateRange} from '../utils/dateTypes';
+import {
+  type PlainDate,
+  plainDateFromISO,
+  plainDateSetFirstOfMonth,
+  plainDateAddMonths,
+  plainDateIsBefore,
+  plainDateIsAfter,
+} from '../utils/plainDate';
+
+export interface InitialFocusDateOptions {
+  /** Controlled visible month, if the consumer supplied one. */
+  focusDate?: ISODateString;
+  /** Selected value (single date or range), controlled or uncontrolled. */
+  value?: ISODateString | DateRange;
+  /** Earliest selectable date. */
+  min?: ISODateString;
+  /** Latest selectable date. */
+  max?: ISODateString;
+  /** How many month panes the calendar renders (1 or 2). */
+  numberOfMonths: number;
+  /** Today, injected so the caller keeps a single memoized source of "now". */
+  today: PlainDate;
+}
+
+/**
+ * Picks the date whose month the calendar opens on.
+ *
+ * An explicit `focusDate` wins, then the selected value — both are the
+ * consumer's own instruction about where to look, so neither is second-guessed
+ * against `min`/`max`.
+ *
+ * Otherwise the calendar opens on today, clamped into the `min`/`max` window.
+ * Without the clamp a window that doesn't contain today (a 2019 audit range, a
+ * booking window opening next spring) opened on today's month with every day
+ * disabled, leaving prev/next clicking as the only way in.
+ *
+ * When clamping forward to `min`, that month leads: the whole selectable window
+ * runs ahead of it. When clamping back to `max`, the last pane lands on `max`'s
+ * month instead — with `numberOfMonths={2}` opening on `[max, max + 1]` would
+ * spend half the calendar on a month that is entirely out of bounds. That
+ * shift never crosses `min`'s month.
+ */
+export function getInitialFocusDate(
+  options: InitialFocusDateOptions,
+): PlainDate {
+  const {focusDate, value, min, max, numberOfMonths, today} = options;
+
+  if (focusDate) {
+    return plainDateFromISO(focusDate);
+  }
+
+  if (value) {
+    return plainDateFromISO(typeof value === 'string' ? value : value.start);
+  }
+
+  const minDate = min ? plainDateFromISO(min) : null;
+  const maxDate = max ? plainDateFromISO(max) : null;
+
+  if (minDate && plainDateIsBefore(today, minDate)) {
+    return minDate;
+  }
+
+  if (maxDate && plainDateIsAfter(today, maxDate)) {
+    const lastPaneOffset = Math.max(0, numberOfMonths - 1);
+    const shifted = plainDateAddMonths(
+      plainDateSetFirstOfMonth(maxDate),
+      -lastPaneOffset,
+    );
+    if (
+      minDate &&
+      plainDateIsBefore(shifted, plainDateSetFirstOfMonth(minDate))
+    ) {
+      return minDate;
+    }
+    return shifted;
+  }
+
+  return today;
+}

package/src/Calendar/styles.ts

@@ -51,19 +51,12 @@ export const calendarStyles = stylex.create({
   },
   monthsContainer: {
     display: 'flex',
+    // Wraps rather than overflowing: two months side by side need ~488px, so
+    // an unwrapped row scrolls the document sideways below that and puts the
+    // next-month button off-viewport (WCAG 1.4.10). Above 488px nothing moves.
+    flexWrap: 'wrap',
     gap: spacingVars['--spacing-4'],
   },
-  srOnly: {
-    position: 'absolute',
-    width: '1px',
-    height: '1px',
-    padding: 0,
-    margin: '-1px',
-    overflow: 'hidden',
-    clip: 'rect(0, 0, 0, 0)',
-    whiteSpace: 'nowrap',
-    borderWidth: 0,
-  },
   /**
    * Wrapper for the month nav chevrons. RTL mirroring is applied by
    * composing the shared `rtlStyles.mirror` transform onto this wrapper
@@ -123,6 +116,17 @@ export const monthGridStyles = stylex.create({
 // Day Cell Styles - Structural (layout, sizing, positioning)
 // =============================================================================
 
+// Half the gap between the day button and its cell — (--size-element-md minus
+// --size-element-sm) / 2 — so the band's rounded caps line up with the button
+// and the button's ::before bleeds out to meet its neighbour's. Deliberately a
+// literal and NOT a spacing token: this is a layout value derived from the two
+// size tokens, and pinning it to --spacing-0-5 desynchronises it from them
+// (matcha sets that step to 3px, which overlaps adjacent days' hit targets by
+// 2px). Deriving it with calc() from the size tokens would be better still and
+// would close butter's 4px dead gap; that needs its own measured change.
+const BAND_INSET = '2px';
+const HIT_BLEED = '-2px';
+
 export const dayCellStyles = stylex.create({
   // Cell container
   cell: {
@@ -137,53 +141,53 @@ export const dayCellStyles = stylex.create({
   // Range background - structural positioning
   rangeBg: {
     position: 'absolute',
-    top: '2px',
-    bottom: '2px',
+    top: BAND_INSET,
+    bottom: BAND_INSET,
     insetInlineStart: 0,
     insetInlineEnd: 0,
   },
   rangeBgRadiusStart: {
-    insetInlineStart: '2px',
+    insetInlineStart: BAND_INSET,
     borderStartStartRadius: radiusVars['--radius-full'],
     borderEndStartRadius: radiusVars['--radius-full'],
   },
   rangeBgRadiusEnd: {
-    insetInlineEnd: '2px',
+    insetInlineEnd: BAND_INSET,
     borderStartEndRadius: radiusVars['--radius-full'],
     borderEndEndRadius: radiusVars['--radius-full'],
   },
   rangeInsetStart: {
-    insetInlineStart: '2px',
+    insetInlineStart: BAND_INSET,
   },
   rangeInsetEnd: {
-    insetInlineEnd: '2px',
+    insetInlineEnd: BAND_INSET,
   },
 
   // Preview background - structural positioning
   previewBg: {
     position: 'absolute',
-    top: '2px',
-    bottom: '2px',
+    top: BAND_INSET,
+    bottom: BAND_INSET,
     insetInlineStart: 0,
     insetInlineEnd: 0,
   },
   previewBgRadiusStart: {
-    insetInlineStart: '2px',
+    insetInlineStart: BAND_INSET,
     borderStartStartRadius: radiusVars['--radius-full'],
     borderEndStartRadius: radiusVars['--radius-full'],
   },
   previewBgRadiusEnd: {
-    insetInlineEnd: '2px',
+    insetInlineEnd: BAND_INSET,
     borderStartEndRadius: radiusVars['--radius-full'],
     borderEndEndRadius: radiusVars['--radius-full'],
   },
   previewStart: {
-    insetInlineStart: '2px',
+    insetInlineStart: BAND_INSET,
     borderStartStartRadius: radiusVars['--radius-full'],
     borderEndStartRadius: radiusVars['--radius-full'],
   },
   previewEnd: {
-    insetInlineEnd: '2px',
+    insetInlineEnd: BAND_INSET,
     borderStartEndRadius: radiusVars['--radius-full'],
     borderEndEndRadius: radiusVars['--radius-full'],
   },
@@ -195,7 +199,7 @@ export const dayCellStyles = stylex.create({
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',
-    borderRadius: '50%',
+    borderRadius: radiusVars['--radius-full'],
     borderWidth: 0,
     borderStyle: 'none',
     cursor: {
@@ -213,14 +217,14 @@ export const dayCellStyles = stylex.create({
     },
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
-    // Expand hit target by 2px on each side to prevent gaps
+    // Expand hit target so adjacent days meet with no gap
     '::before': {
       content: '""',
       position: 'absolute',
-      top: '-2px',
-      insetInlineEnd: '-2px',
-      bottom: '-2px',
-      insetInlineStart: '-2px',
+      top: HIT_BLEED,
+      insetInlineEnd: HIT_BLEED,
+      bottom: HIT_BLEED,
+      insetInlineStart: HIT_BLEED,
     },
   },
 
@@ -280,8 +284,22 @@ export const dayCellTheme = stylex.create({
 
   // Selected state (single selection or range endpoints)
   daySelected: {
-    backgroundColor: colorVars['--color-accent'],
-    color: colorVars['--color-on-accent'],
+    // Forced colors (Windows High Contrast) strips the accent fill, which
+    // leaves the selected date looking exactly like every other day.
+    // Highlight/HighlightText is the platform convention for a selected
+    // control (WCAG 1.4.11), and `forced-color-adjust: none` is required
+    // because this is a <button>: the UA otherwise keeps the native
+    // ButtonFace surface and ignores the authored fill, the same trap
+    // ToggleButton documents.
+    forcedColorAdjust: 'none',
+    backgroundColor: {
+      default: colorVars['--color-accent'],
+      '@media (forced-colors: active)': 'Highlight',
+    },
+    color: {
+      default: colorVars['--color-on-accent'],
+      '@media (forced-colors: active)': 'HighlightText',
+    },
     backgroundImage: {
       default: null,
       ':hover:where(:not(:disabled,[aria-disabled="true"]))': {

package/src/Card/Card.doc.mjs

@@ -57,8 +57,9 @@ export const docs = {
     {
       name: 'padding',
       type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
-      description: 'Internal padding using the spacing scale.',
-      default: '4',
+      description:
+        "Internal padding using the spacing scale. Omit it and the card takes the theme's card padding rather than a step, so passing a step is a decision to override the theme, not a way to restate the default.",
+      default: "the theme's card padding (spacing step 4 with no theme)",
     },
     {
       name: 'variant',
@@ -77,7 +78,6 @@ export const docs = {
   ],
   playground: {
     defaults: {
-      padding: 4,
       children: {
         __element: 'VStack',
         props: {gap: 2},
@@ -91,7 +91,7 @@ export const docs = {
   theming: {
     container: true,
     targets: [
-      {className: 'astryx-card', visualProps: ['variant']},
+      {className: 'astryx-card', visualProps: ['variant', 'elevation']},
     ],
     vars: [
       {name: '--_card-radius', description: 'Border radius of the card', default: 'var(--radius-container)', private: true},
@@ -135,16 +135,19 @@ export const docsZh = {
     {name: 'maxWidth', type: 'SizeValue', description: '卡片最大宽度。'},
     {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: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: '使用间距比例的内边距。省略时，卡片采用主题的卡片内边距，而不是某个步进值；传入步进值意味着覆盖主题，而不是复述默认值。', default: "the theme's card padding (spacing step 4 with no theme)"},
+    {name: 'variant', type: "'default' | 'transparent' | 'muted' | 'blue' | 'cyan' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'", description: '背景颜色变体。`default` 使用标准卡片背景；`transparent` 完全去掉背景；`muted` 使用弱化卡片的柔和背景。非语义变体使用对应的 `--color-background-<name>` 令牌。', default: "'default'"},
     {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。`none` 为扁平；`low`/`med`/`high` 对应阴影令牌比例。', default: "'none'"},
   ],
   theming: {
     container: true,
     targets: [
-      {className: 'astryx-card', visualProps: ['variant']},
+      {className: 'astryx-card', visualProps: ['variant', 'elevation']},
     ],
     vars: [
       {name: '--_card-radius', description: 'Border radius of the card', default: 'var(--radius-container)', private: true},
+      {name: '--_card-elevation', description: 'Resting shadow of the card, set from the elevation prop.', default: '0 0 transparent', private: true},
+      {name: '--_card-ring', description: 'Inset ring drawn in the card box-shadow list.', default: '0 0 transparent', private: true},
     ],
     derived: [
       {property: 'borderRadius', vars: ['--_card-radius']},
@@ -178,7 +181,7 @@ export const docsDense = {
     maxWidth: 'max card width',
     minHeight: 'min card height',
     children: 'content inside card',
-    padding: 'internal padding via spacing scale',
+    padding: "internal padding via spacing scale; omitted = the theme's card padding, NOT a fixed step. Passing a step overrides the theme.",
     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.',
   },