@astryxdesign/core 0.5.0-canary.8985bb9 → 0.5.0-canary.955ecef

package/dist/AlertDialog/AlertDialog.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file AlertDialog.tsx
- * @input Uses React, Dialog, Layout, Heading, Text, Button
+ * @input Uses React, StyleX, Dialog, Layout, Heading, Text, Button
  * @output Exports AlertDialog component, AlertDialogProps type
  * @position Core implementation; consumed by index.ts, tested by AlertDialog.test.tsx
  *

package/dist/AlertDialog/AlertDialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AlertDialog.d.ts","sourceRoot":"","sources":["../../src/AlertDialog/AlertDialog.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAA2B,MAAM,OAAO,CAAC;AAQhD,OAAO,EAAS,KAAK,aAAa,EAAC,MAAM,WAAW,CAAC;AACrD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAK5C,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IACpE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAE3C;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,QAAQ,EAAE,MAAM,OAAO,CAAC;IAExB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,GAAG,EACH,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,KAAK,EACL,WAAW,EACX,WAAW,EAAE,oBAAoB,EACjC,WAAW,EACX,aAA6B,EAC7B,eAAe,EACf,QAAQ,EACR,KAAW,EACX,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,IAAI,EACR,EAAE,gBAAgB,qBAkElB;yBApFe,WAAW"}
+{"version":3,"file":"AlertDialog.d.ts","sourceRoot":"","sources":["../../src/AlertDialog/AlertDialog.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAA2B,MAAM,OAAO,CAAC;AAShD,OAAO,EAAS,KAAK,aAAa,EAAC,MAAM,WAAW,CAAC;AACrD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAkB5C,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IACpE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAE3C;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,QAAQ,EAAE,MAAM,OAAO,CAAC;IAExB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,GAAG,EACH,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,KAAK,EACL,WAAW,EACX,WAAW,EAAE,oBAAoB,EACjC,WAAW,EACX,aAA6B,EAC7B,eAAe,EACf,QAAQ,EACR,KAAW,EACX,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,IAAI,EACR,EAAE,gBAAgB,qBA8FlB;yBAhHe,WAAW"}

package/dist/AlertDialog/AlertDialog.js

@@ -4,7 +4,7 @@
 
 /**
  * @file AlertDialog.tsx
- * @input Uses React, Dialog, Layout, Heading, Text, Button
+ * @input Uses React, StyleX, Dialog, Layout, Heading, Text, Button
  * @output Exports AlertDialog component, AlertDialogProps type
  * @position Core implementation; consumed by index.ts, tested by AlertDialog.test.tsx
  *
@@ -16,18 +16,32 @@
  * - /packages/cli/assets/templates/blocks/components/AlertDialog/ (showcase blocks)
  */
 import React, { useId, useCallback } from 'react';
+import * as stylex from '@stylexjs/stylex';
 import { Dialog } from "../Dialog/index.js";
 import { Layout } from "../Layout/Layout.js";
 import { LayoutContent } from "../Layout/LayoutContent.js";
 import { LayoutFooter } from "../Layout/LayoutFooter.js";
-import { HStack } from "../Stack/index.js";
+import { Stack } from "../Stack/index.js";
 import { Heading } from "../Heading/Heading.js";
 import { Text } from "../Text/Text.js";
 import { Button } from "../Button/index.js";
 import { mergeProps } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useTranslator } from "../i18n/index.js";
+import { useMediaQuery } from "../hooks/index.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const SMALL_SCREEN_QUERY = '(max-width: 640px)';
+const styles = {
+  action: {
+    ks0D6T: "x193iq5w",
+    k7Eaqz: "xeuugli",
+    $$css: true
+  },
+  stackedAction: {
+    kzqmXN: "xh8yej3",
+    $$css: true
+  }
+};
 /**
  * A confirmation dialog for destructive or irreversible actions.
  *
@@ -77,9 +91,33 @@ export function AlertDialog({
   const cancelLabel = cancelLabelFromProps ?? t('@astryx.alertDialog.cancel');
   const titleId = useId();
   const descriptionId = useId();
+  // Width stays delegated to Dialog: this query exists only so AlertDialog can
+  // keep narrow visual, DOM, and tab order aligned for its destructive/cancel
+  // semantics without coupling action order to pointer or hover capability.
+  const isSmallScreen = useMediaQuery(SMALL_SCREEN_QUERY);
   const handleCancel = useCallback(() => {
     onOpenChange(false);
   }, [onOpenChange]);
+  const buttonActionStyle = [styles.action, isSmallScreen && styles.stackedAction];
+  const cancelButton = /*#__PURE__*/_jsx(Button, {
+    variant: "ghost",
+    label: cancelLabel,
+    onClick: handleCancel,
+    xstyle: buttonActionStyle
+    // Dialog focuses [data-autofocus] itself after showModal(), because
+    // React's autoFocus runs during commit while the dialog is invisible.
+    // Cancel is least destructive, so it remains the autofocus target even
+    // when small-screen visual order places the destructive action above it.
+    ,
+    "data-autofocus": true
+  }, "cancel");
+  const actionButton = /*#__PURE__*/_jsx(Button, {
+    variant: actionVariant,
+    label: actionLabel,
+    onClick: onAction,
+    isLoading: isActionLoading,
+    xstyle: buttonActionStyle
+  }, "action");
   return /*#__PURE__*/_jsx(Dialog, {
     ...rest,
     ref: ref,
@@ -117,25 +155,12 @@ export function AlertDialog({
         })]
       }),
       footer: /*#__PURE__*/_jsx(LayoutFooter, {
-        children: /*#__PURE__*/_jsxs(HStack, {
+        children: /*#__PURE__*/_jsx(Stack, {
+          direction: isSmallScreen ? 'vertical' : 'horizontal',
           gap: 2,
-          hAlign: "end",
-          children: [/*#__PURE__*/_jsx(Button, {
-            variant: "ghost",
-            label: cancelLabel,
-            onClick: handleCancel
-            // Dialog focuses [data-autofocus] itself after showModal(),
-            // because React's autoFocus runs during commit while the
-            // dialog is still invisible. Cancel is the least destructive
-            // choice, so it is the one that should be preselected.
-            ,
-            "data-autofocus": true
-          }), /*#__PURE__*/_jsx(Button, {
-            variant: actionVariant,
-            label: actionLabel,
-            onClick: onAction,
-            isLoading: isActionLoading
-          })]
+          hAlign: isSmallScreen ? 'stretch' : 'end',
+          wrap: isSmallScreen ? 'nowrap' : 'wrap',
+          children: isSmallScreen ? [actionButton, cancelButton] : [cancelButton, actionButton]
         })
       })
     })

package/dist/Card/Card.d.ts

@@ -30,14 +30,6 @@ export type CardVariant = 'default' | 'transparent' | 'muted' | 'blue' | 'cyan'
 export type { SizeValue } from '../utils/types';
 export interface CardProps extends BaseProps<HTMLDivElement> {
     ref?: React.Ref<HTMLDivElement>;
-    /**
-     * CSS class name(s) appended to the root element.
-     */
-    className?: string;
-    /**
-     * Inline styles to apply to the root element.
-     */
-    style?: React.CSSProperties;
     /**
      * Width of the card.
      * Numbers are treated as pixels, strings are used as-is.
@@ -66,7 +58,12 @@ export interface CardProps extends BaseProps<HTMLDivElement> {
     /**
      * Internal padding of the card using the spacing scale.
      * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
-     * @default 4 (16px)
+     *
+     * 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)
      */
     padding?: SpacingStep;
     /**

package/dist/Card/Card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Card.d.ts","sourceRoot":"","sources":["../../src/Card/Card.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAiBrC,OAAO,KAAK,EAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAEtE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAO5C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GACnB,SAAS,GACT,aAAa,GACb,OAAO,GACP,MAAM,GACN,MAAM,GACN,MAAM,GACN,OAAO,GACP,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,KAAK,GACL,MAAM,GACN,QAAQ,CAAC;AA2Gb,YAAY,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAE9C,MAAM,WAAW,SAAU,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC1D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,IAAI,CAAC,EACnB,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,OAAO,EACP,OAAmB,EACnB,SAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,SAAS,+BA2DX;yBAzEe,IAAI"}
+{"version":3,"file":"Card.d.ts","sourceRoot":"","sources":["../../src/Card/Card.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAWrC,OAAO,KAAK,EAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAEtE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAO5C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GACnB,SAAS,GACT,aAAa,GACb,OAAO,GACP,MAAM,GACN,MAAM,GACN,MAAM,GACN,OAAO,GACP,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,KAAK,GACL,MAAM,GACN,QAAQ,CAAC;AA2Gb,YAAY,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAE9C,MAAM,WAAW,SAAU,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC1D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,IAAI,CAAC,EACnB,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,OAAO,EACP,OAAmB,EACnB,SAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,SAAS,+BAgDX;yBA9De,IAAI"}

package/dist/Card/Card.js

@@ -17,7 +17,7 @@ import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { borderVars, colorVars, radiusVars, shadowVars } from "../theme/tokens.stylex.js";
 import { container } from "../Layout/container.stylex.js";
-import { paddingStyles, containerPaddingInlineVarStyles, containerPaddingBlockStartVarStyles, containerPaddingBlockEndVarStyles, spacingStepToToken } from "../Layout/padding.stylex.js";
+import { spacingStepToToken } from "../Layout/padding.stylex.js";
 import { mergeProps } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 
@@ -216,20 +216,20 @@ export function Card({
 
   // When no explicit padding prop, use theme default (set via container tokens)
   const useThemeDefault = padding == null;
-  const effectivePadding = padding ?? 4;
-  const paddingToken = spacingStepToToken[effectivePadding];
+  const paddingToken = useThemeDefault ? undefined : spacingStepToToken[padding];
   return /*#__PURE__*/_jsx("div", {
     ref: ref,
     ...mergeProps(themeProps('card', {
-      variant
-    }), stylex.props(styles.card, variantStyles[variant], elevationStyles[elevation], hasFixedHeight && styles.scrollable, dynamicStyles.sizing(width ?? null, height ?? null, maxWidth ?? null, minHeight ?? null), ...container(useThemeDefault ? {
+      variant,
+      elevation
+    }), stylex.props(styles.card, variantStyles[variant], elevationStyles[elevation], hasFixedHeight && styles.scrollable, dynamicStyles.sizing(width ?? null, height ?? null, maxWidth ?? null, minHeight ?? null), ...container(paddingToken == null ? {
       useThemeDefault: 'card'
     } : {
       paddingInnerX: paddingToken,
       paddingInnerY: paddingToken,
       paddingOuterX: paddingToken,
       paddingOuterY: paddingToken
-    }), !useThemeDefault && effectivePadding !== 4 && paddingStyles[effectivePadding], !useThemeDefault && effectivePadding !== 4 && containerPaddingInlineVarStyles[effectivePadding], !useThemeDefault && effectivePadding !== 4 && containerPaddingBlockStartVarStyles[effectivePadding], !useThemeDefault && effectivePadding !== 4 && containerPaddingBlockEndVarStyles[effectivePadding],
+    }),
     // Applied after the container padding so the border-inset calc wins;
     // it reads the --container-padding-* vars set above.
     variant === 'default' && styles.withBorder, xstyle), className, style),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.5.0-canary.8985bb9",
+  "version": "0.5.0-canary.955ecef",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -661,7 +661,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/cli": "0.5.0-canary.8985bb9",
+    "@astryxdesign/cli": "0.5.0-canary.955ecef",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",

package/src/AlertDialog/AlertDialog.doc.mjs

@@ -21,21 +21,75 @@ export const docs = {
   ],
   usage: {
     description:
-      'AlertDialog asks the user to confirm a destructive or irreversible action before it happens. Use it for things like deleting content, revoking access, or discarding unsaved changes.\n\nIt implements the WAI-ARIA APG [Alert Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/): `role="alertdialog"`, a title linked by `aria-labelledby`, a consequence description linked by `aria-describedby`, focus moved into the dialog on open and returned to the trigger on close, and no dismissal by clicking outside. Escape cancels.\n\nFor cases where you want to show an alert without managing open state, use the `useImperativeAlertDialog` hook: call `alert.show(options)` and render `alert.element` in your tree.',
+      'AlertDialog asks the user to confirm a destructive or irreversible action before it happens. Use it for things like deleting content, revoking access, or discarding unsaved changes.\n\nIt implements the WAI-ARIA APG [Alert Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/): `role="alertdialog"`, a title linked by `aria-labelledby`, a consequence description linked by `aria-describedby`, focus moved into the dialog on open and returned to the trigger on close, and no dismissal by clicking outside. Escape cancels.\n\nAlertDialog passes its requested width through to Dialog, which clamps the surface to the container and dynamic viewport with token gutters. Generic Dialog footers should wrap, but Dialog does not own action semantics or order; consumer composition controls that. AlertDialog owns its confirmation semantics: above 640px, actions render horizontally and may move onto another row; at 640px and below, the destructive action appears above Cancel and both buttons fill the footer width. Button labels retain their standard single-line behavior. The breakpoint follows available width, not pointer or hover capability. The body scrolls when block space is constrained.\n\nFor cases where you want to show an alert without managing open state, use the `useImperativeAlertDialog` hook: call `alert.show(options)` and render `alert.element` in your tree.',
     bestPractices: [
-      {guidance: true, description: 'Make the action button label specific: "Delete project" is better than "OK" or "Confirm".'},
-      {guidance: true, description: 'Describe what will happen in the description so the user knows the consequences before confirming.'},
-      {guidance: true, description: 'Keep the cancel button first: it takes initial focus, so the least destructive choice is the one already selected when the dialog opens.'},
-      {guidance: false, description: 'Use AlertDialog for non-destructive actions; use a standard Dialog instead.'},
-      {guidance: false, description: 'Rely on color alone to signal danger; the action label itself should say what will happen.'},
-      {guidance: false, description: 'Close the dialog from onAction before the work finishes; hold it open with isActionLoading and call onOpenChange(false) when the action settles.'},
+      {
+        guidance: true,
+        description:
+          'Make the action button label specific: "Delete project" is better than "OK" or "Confirm".',
+      },
+      {
+        guidance: true,
+        description:
+          'Describe what will happen in the description so the user knows the consequences before confirming.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep the cancel button as the least-destructive focus target. On narrow screens the destructive action is visually and structurally above Cancel, but Cancel still receives initial focus.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use concise, specific action labels. Above 640px, complete buttons may move onto another row; at 640px and below, the destructive action appears above Cancel and both buttons fill the footer width.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use AlertDialog for non-destructive actions; use a standard Dialog instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Rely on color alone to signal danger; the action label itself should say what will happen.',
+      },
+      {
+        guidance: false,
+        description:
+          'Close the dialog from onAction before the work finishes; hold it open with isActionLoading and call onOpenChange(false) when the action settles.',
+      },
     ],
     anatomy: [
-      {name: 'Title', required: true, description: 'The question being asked. Renders as a level-2 heading and labels the dialog via aria-labelledby.'},
-      {name: 'Description', required: true, description: 'What will happen if the user confirms. Linked to the dialog via aria-describedby.'},
-      {name: 'Cancel button', required: true, description: 'Ghost button that dismisses without acting. Takes initial focus, and Escape does the same thing.'},
-      {name: 'Action button', required: true, description: 'The confirming action. Destructive by default; shows a spinner while isActionLoading is set.'},
-      {name: 'Backdrop', required: true, description: 'Overlay behind the dialog that blocks page interaction. Clicking it does not dismiss.'},
+      {
+        name: 'Title',
+        required: true,
+        description:
+          'The question being asked. Renders as a level-2 heading and labels the dialog via aria-labelledby.',
+      },
+      {
+        name: 'Description',
+        required: true,
+        description:
+          'What will happen if the user confirms. Linked to the dialog via aria-describedby.',
+      },
+      {
+        name: 'Cancel button',
+        required: true,
+        description:
+          'Ghost button that dismisses without acting. Takes initial focus, and Escape does the same thing.',
+      },
+      {
+        name: 'Action button',
+        required: true,
+        description:
+          'The confirming action. Destructive by default; shows a spinner while isActionLoading is set.',
+      },
+      {
+        name: 'Backdrop',
+        required: true,
+        description:
+          'Overlay behind the dialog that blocks page interaction. Clicking it does not dismiss.',
+      },
     ],
   },
   // Intentionally a contained isInline preview, not playground.overlay: the
@@ -48,11 +102,13 @@ export const docs = {
       isInline: true,
       onOpenChange: undefined,
       title: 'Delete item?',
-      description: 'This action cannot be undone. The item and all its data will be permanently removed.',
+      description:
+        'This action cannot be undone. The item and all its data will be permanently removed.',
       actionLabel: 'Delete',
     },
   },
-  description: 'A modal dialog that asks the user to confirm a destructive action.',
+  description:
+    'A modal dialog that asks the user to confirm a destructive action.',
   props: [
     {
       name: 'isOpen',
@@ -111,38 +167,66 @@ export const docs = {
       name: 'width',
       type: 'number | string',
       default: '400',
-      description: 'Dialog width.',
+      description:
+        'Requested dialog width. Dialog preserves this preferred width and clamps it to the container and dynamic viewport with token gutters.',
     },
     {
       name: 'isInline',
       type: 'boolean',
       default: 'false',
-      description: 'Renders alert dialog content inline without modal behavior. For documentation previews and showcases only. Not being a modal, the inline path renders role="group" instead of role="alertdialog".',
+      description:
+        'Renders alert dialog content inline without modal behavior. For documentation previews and showcases only. Not being a modal, the inline path renders role="group" instead of role="alertdialog".',
     },
   ],
-  components: [
-    {name: 'useImperativeAlertDialog'},
-  ],
+  components: [{name: 'useImperativeAlertDialog'}],
   theming: {
-    targets: [
-      {className: 'astryx-alert-dialog'},
-    ],
+    targets: [{className: 'astryx-alert-dialog'}],
   },
 };
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
-  description: 'Confirms destructive/irreversible action before it happens (delete, revoke access, discard unsaved changes).',
+  description:
+    'Confirms destructive/irreversible action before it happens (delete, revoke access, discard unsaved changes).',
   usage: {
     description:
-      'AlertDialog confirms destructive/irreversible action (delete, revoke access, discard changes). Implements WAI-ARIA APG Alert Dialog pattern (https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/): role="alertdialog", aria-labelledby title, aria-describedby description, focus into dialog on open + back to trigger on close, no outside-click dismissal, Escape cancels. To show w/o managing open state, use useImperativeAlertDialog hook: call alert.show(options) + render alert.element in tree.',
+      'AlertDialog confirms destructive/irreversible action (delete, revoke access, discard changes). Implements WAI-ARIA APG Alert Dialog pattern (https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/): role="alertdialog", aria-labelledby title, aria-describedby description, focus into dialog on open + back to trigger on close, no outside-click dismissal, Escape cancels. Dialog preserves requested width + clamps it to container/dynamic viewport gutters. Generic Dialog footers wrap while consumers own action order. AlertDialog owns confirmation action layout: >640px horizontal buttons may move to another row; <=640px puts the destructive action above Cancel and makes both buttons full width regardless of pointer/hover capability. Button labels remain single-line. Body scrolls when height constrained. To show w/o managing open state, use useImperativeAlertDialog hook: call alert.show(options) + render alert.element in tree.',
     bestPractices: [
-      {guidance: true, description: 'Make action button label specific: "Delete project" > "OK"/"Confirm".'},
-      {guidance: true, description: 'Describe consequences in description so user knows outcome before confirming.'},
-      {guidance: true, description: 'Keep cancel first: it takes initial focus, so least destructive choice is preselected.'},
-      {guidance: false, description: 'Use AlertDialog for non-destructive actions; use standard Dialog instead.'},
-      {guidance: false, description: 'Rely on color alone for danger; the action label should say what happens.'},
-      {guidance: false, description: 'Close from onAction before work finishes; hold open w/ isActionLoading, call onOpenChange(false) when it settles.'},
+      {
+        guidance: true,
+        description:
+          'Make action button label specific: "Delete project" > "OK"/"Confirm".',
+      },
+      {
+        guidance: true,
+        description:
+          'Describe consequences in description so user knows outcome before confirming.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep cancel as initial focus: least destructive choice is preselected even when narrow visual/DOM order places it after the destructive action.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use concise action labels; >640px complete buttons may move to another row, and <=640px puts the destructive action above Cancel with both buttons full width regardless of pointer type.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use AlertDialog for non-destructive actions; use standard Dialog instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Rely on color alone for danger; the action label should say what happens.',
+      },
+      {
+        guidance: false,
+        description:
+          'Close from onAction before work finishes; hold open w/ isActionLoading, call onOpenChange(false) when it settles.',
+      },
     ],
   },
 };

package/src/AlertDialog/AlertDialog.test.tsx

@@ -9,12 +9,65 @@
  * SYNC: When AlertDialog.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {
+  render,
+  screen,
+  fireEvent,
+  waitFor,
+  within,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {AlertDialog} from './AlertDialog';
 import {useImperativeAlertDialog} from './useImperativeAlertDialog';
 
+function stubAlertDialogMedia({
+  smallScreen,
+  coarsePointer,
+  noHover,
+  reduceMotion = false,
+}: {
+  smallScreen: boolean;
+  coarsePointer: boolean;
+  noHover: boolean;
+  reduceMotion?: boolean;
+}): void {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn((query: string) => {
+      let matches = false;
+      if (query.includes('max-width: 640px')) {
+        matches = smallScreen;
+      } else if (query.includes('pointer: coarse')) {
+        matches = coarsePointer;
+      } else if (query.includes('pointer: fine')) {
+        matches = !coarsePointer;
+      } else if (query.includes('hover: none')) {
+        matches = noHover;
+      } else if (query.includes('hover: hover')) {
+        matches = !noHover;
+      } else if (query.includes('prefers-reduced-motion: reduce')) {
+        matches = reduceMotion;
+      } else if (query.includes('prefers-reduced-motion: no-preference')) {
+        matches = !reduceMotion;
+      } else if (query.includes('prefers-reduced-motion')) {
+        matches = reduceMotion;
+      }
+
+      return {
+        matches,
+        media: query,
+        onchange: null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      };
+    }),
+  );
+}
+
 beforeEach(() => {
   HTMLDialogElement.prototype.showModal = vi.fn(function (
     this: HTMLDialogElement,
@@ -26,6 +79,10 @@ beforeEach(() => {
   });
 });
 
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
 describe('AlertDialog', () => {
   const defaultProps = {
     isOpen: true,
@@ -109,6 +166,158 @@ describe('AlertDialog', () => {
     expect(screen.getByRole('alertdialog')).toBeInTheDocument();
   });
 
+  describe('responsive actions', () => {
+    const longCancelLabel = 'Keep this workspace and all of its dashboards';
+    const longActionLabel =
+      'Permanently delete this workspace and all dashboards';
+
+    it('preserves the preferred width and horizontal order above the small breakpoint', () => {
+      stubAlertDialogMedia({
+        smallScreen: false,
+        coarsePointer: false,
+        noHover: false,
+      });
+      render(<AlertDialog {...defaultProps} />);
+
+      expect(window.matchMedia).toHaveBeenCalledWith('(max-width: 640px)');
+      expect(window.matchMedia).not.toHaveBeenCalledWith('(pointer: coarse)');
+      expect(window.matchMedia).not.toHaveBeenCalledWith('(hover: none)');
+      const dialog = screen.getByRole('alertdialog');
+      const buttons = within(dialog).getAllByRole('button');
+      const footerStack = buttons[0].parentElement!;
+      expect(dialog.getAttribute('style')).toContain('--x-width: 400px');
+      expect(dialog.getAttribute('style')).toContain(
+        '--x-maxWidth: min(100%, calc(100dvw - var(--spacing-4) - var(--spacing-4)))',
+      );
+      expect(buttons.map(button => button.textContent)).toEqual([
+        'Cancel',
+        'Delete',
+      ]);
+      expect(getComputedStyle(footerStack).flexWrap).toBe('wrap');
+    });
+
+    it('keeps long action buttons within the wide horizontal footer without changing Button sizing', () => {
+      stubAlertDialogMedia({
+        smallScreen: false,
+        coarsePointer: false,
+        noHover: false,
+      });
+      render(
+        <AlertDialog
+          {...defaultProps}
+          cancelLabel={longCancelLabel}
+          actionLabel={longActionLabel}
+        />,
+      );
+
+      const dialog = screen.getByRole('alertdialog');
+      const buttons = within(dialog).getAllByRole('button');
+      const footerStack = buttons[0].parentElement!;
+      expect(buttons.map(button => button.textContent)).toEqual([
+        longCancelLabel,
+        longActionLabel,
+      ]);
+      expect(getComputedStyle(footerStack).flexWrap).toBe('wrap');
+      for (const button of buttons) {
+        const computed = getComputedStyle(button);
+        expect(computed.whiteSpace).toBe('nowrap');
+        expect(computed.height).toBe('var(--size-element-md)');
+        expect(computed.maxWidth).toBe('100%');
+      }
+    });
+
+    it('stacks long destructive action labels above cancel on a narrow fine-pointer screen', () => {
+      stubAlertDialogMedia({
+        smallScreen: true,
+        coarsePointer: false,
+        noHover: false,
+      });
+      render(
+        <AlertDialog
+          {...defaultProps}
+          cancelLabel={longCancelLabel}
+          actionLabel={longActionLabel}
+        />,
+      );
+
+      expect(window.matchMedia).toHaveBeenCalledWith('(max-width: 640px)');
+      expect(window.matchMedia).not.toHaveBeenCalledWith('(pointer: coarse)');
+      expect(window.matchMedia).not.toHaveBeenCalledWith('(hover: none)');
+      const dialog = screen.getByRole('alertdialog');
+      const buttons = within(dialog).getAllByRole('button');
+      const footerStack = buttons[0].parentElement!;
+      expect(dialog.getAttribute('style')).toContain('--x-width: 400px');
+      expect(buttons.map(button => button.textContent)).toEqual([
+        longActionLabel,
+        longCancelLabel,
+      ]);
+      expect(getComputedStyle(footerStack).flexDirection).toBe('column');
+      for (const button of buttons) {
+        const computed = getComputedStyle(button);
+        expect(computed.whiteSpace).toBe('nowrap');
+        expect(computed.width).toBe('100%');
+        expect(computed.maxWidth).toBe('100%');
+      }
+    });
+
+    it('uses the same stacked layout on a mobile touch screen', () => {
+      stubAlertDialogMedia({
+        smallScreen: true,
+        coarsePointer: true,
+        noHover: true,
+      });
+      render(
+        <AlertDialog
+          {...defaultProps}
+          cancelLabel="Keep this workspace"
+          actionLabel="Permanently delete workspace"
+        />,
+      );
+
+      expect(window.matchMedia).toHaveBeenCalledWith('(max-width: 640px)');
+      expect(window.matchMedia).not.toHaveBeenCalledWith('(pointer: coarse)');
+      expect(window.matchMedia).not.toHaveBeenCalledWith('(hover: none)');
+      const dialog = screen.getByRole('alertdialog');
+      const buttons = within(dialog).getAllByRole('button');
+      expect(dialog.getAttribute('style')).toContain('--x-width: 400px');
+      expect(buttons.map(button => button.textContent)).toEqual([
+        'Permanently delete workspace',
+        'Keep this workspace',
+      ]);
+      expect(getComputedStyle(buttons[0]).whiteSpace).toBe('nowrap');
+      expect(getComputedStyle(buttons[0]).width).toBe('100%');
+      expect(getComputedStyle(buttons[1]).whiteSpace).toBe('nowrap');
+      expect(getComputedStyle(buttons[1]).width).toBe('100%');
+    });
+
+    it('keeps narrow visual, DOM, and tab order aligned while autofocus stays on cancel', async () => {
+      const user = userEvent.setup();
+      stubAlertDialogMedia({
+        smallScreen: true,
+        coarsePointer: false,
+        noHover: false,
+      });
+      render(
+        <AlertDialog
+          {...defaultProps}
+          cancelLabel={longCancelLabel}
+          actionLabel={longActionLabel}
+        />,
+      );
+
+      const action = screen.getByRole('button', {name: longActionLabel});
+      const cancel = screen.getByRole('button', {name: longCancelLabel});
+      expect(
+        action.compareDocumentPosition(cancel) &
+          Node.DOCUMENT_POSITION_FOLLOWING,
+      ).toBeTruthy();
+      expect(cancel).toHaveAttribute('data-autofocus');
+      action.focus();
+      await user.tab();
+      expect(cancel).toHaveFocus();
+    });
+  });
+
   it('defaults cancel label to Cancel', () => {
     render(<AlertDialog {...defaultProps} />);
     expect(screen.getByText('Cancel')).toBeInTheDocument();

package/src/AlertDialog/AlertDialog.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file AlertDialog.tsx
- * @input Uses React, Dialog, Layout, Heading, Text, Button
+ * @input Uses React, StyleX, Dialog, Layout, Heading, Text, Button
  * @output Exports AlertDialog component, AlertDialogProps type
  * @position Core implementation; consumed by index.ts, tested by AlertDialog.test.tsx
  *
@@ -17,11 +17,12 @@
  */
 
 import React, {useId, useCallback} from 'react';
+import * as stylex from '@stylexjs/stylex';
 import {Dialog} from '../Dialog';
 import {Layout} from '../Layout/Layout';
 import {LayoutContent} from '../Layout/LayoutContent';
 import {LayoutFooter} from '../Layout/LayoutFooter';
-import {HStack} from '../Stack';
+import {Stack} from '../Stack';
 import {Heading} from '../Heading/Heading';
 import {Text} from '../Text/Text';
 import {Button, type ButtonVariant} from '../Button';
@@ -29,6 +30,19 @@ import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
+import {useMediaQuery} from '../hooks';
+
+const SMALL_SCREEN_QUERY = '(max-width: 640px)';
+
+const styles = stylex.create({
+  action: {
+    maxWidth: '100%',
+    minWidth: 0,
+  },
+  stackedAction: {
+    width: '100%',
+  },
+});
 
 export interface AlertDialogProps extends BaseProps<HTMLDialogElement> {
   ref?: React.Ref<HTMLDialogElement>;
@@ -147,11 +161,44 @@ export function AlertDialog({
   const cancelLabel = cancelLabelFromProps ?? t('@astryx.alertDialog.cancel');
   const titleId = useId();
   const descriptionId = useId();
+  // Width stays delegated to Dialog: this query exists only so AlertDialog can
+  // keep narrow visual, DOM, and tab order aligned for its destructive/cancel
+  // semantics without coupling action order to pointer or hover capability.
+  const isSmallScreen = useMediaQuery(SMALL_SCREEN_QUERY);
 
   const handleCancel = useCallback(() => {
     onOpenChange(false);
   }, [onOpenChange]);
 
+  const buttonActionStyle = [
+    styles.action,
+    isSmallScreen && styles.stackedAction,
+  ];
+  const cancelButton = (
+    <Button
+      key="cancel"
+      variant="ghost"
+      label={cancelLabel}
+      onClick={handleCancel}
+      xstyle={buttonActionStyle}
+      // Dialog focuses [data-autofocus] itself after showModal(), because
+      // React's autoFocus runs during commit while the dialog is invisible.
+      // Cancel is least destructive, so it remains the autofocus target even
+      // when small-screen visual order places the destructive action above it.
+      data-autofocus
+    />
+  );
+  const actionButton = (
+    <Button
+      key="action"
+      variant={actionVariant}
+      label={actionLabel}
+      onClick={onAction}
+      isLoading={isActionLoading}
+      xstyle={buttonActionStyle}
+    />
+  );
+
   return (
     <Dialog
       {...rest}
@@ -185,24 +232,19 @@ export function AlertDialog({
         }
         footer={
           <LayoutFooter>
-            <HStack gap={2} hAlign="end">
-              <Button
-                variant="ghost"
-                label={cancelLabel}
-                onClick={handleCancel}
-                // Dialog focuses [data-autofocus] itself after showModal(),
-                // because React's autoFocus runs during commit while the
-                // dialog is still invisible. Cancel is the least destructive
-                // choice, so it is the one that should be preselected.
-                data-autofocus
-              />
-              <Button
-                variant={actionVariant}
-                label={actionLabel}
-                onClick={onAction}
-                isLoading={isActionLoading}
-              />
-            </HStack>
+            {/* Generic Dialog footers should wrap, but their consumers own
+                action semantics and order. AlertDialog keeps this
+                destructive-above-Cancel narrow order because confirmation
+                actions have component-specific meaning here. */}
+            <Stack
+              direction={isSmallScreen ? 'vertical' : 'horizontal'}
+              gap={2}
+              hAlign={isSmallScreen ? 'stretch' : 'end'}
+              wrap={isSmallScreen ? 'nowrap' : 'wrap'}>
+              {isSmallScreen
+                ? [actionButton, cancelButton]
+                : [cancelButton, actionButton]}
+            </Stack>
           </LayoutFooter>
         }
       />

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.',
   },

package/src/Card/Card.test.tsx

@@ -1,5 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+import {createRef} from 'react';
 import {describe, it, expect} from 'vitest';
 import {render} from '@testing-library/react';
 import {Card} from './Card';
@@ -10,17 +11,52 @@ describe('Card', () => {
     expect(getByText('Hello')).toBeInTheDocument();
   });
 
-  it('renders astryx-* class names for theme targeting', () => {
-    const {container} = render(<Card>Content</Card>);
-    const root = container.firstElementChild!;
+  it('forwards ref to the rendered element', () => {
+    const ref = createRef<HTMLDivElement>();
+    const {container} = render(<Card ref={ref}>C</Card>);
+    expect(ref.current).toBe(container.firstElementChild);
+  });
+
+  it('spreads unknown props onto the same element that carries the theme target', () => {
+    const {getByTestId} = render(
+      <Card data-testid="card" id="promo" aria-label="Promotion">
+        C
+      </Card>,
+    );
+    const root = getByTestId('card');
+    expect(root).toHaveAttribute('id', 'promo');
+    expect(root).toHaveAttribute('aria-label', 'Promotion');
     expect(root.className).toContain('astryx-card');
   });
 
-  it('renders transparent variant with variant class', () => {
-    const {container} = render(<Card variant="transparent">Content</Card>);
+  it('merges a consumer className instead of replacing the theme target', () => {
+    const {container} = render(<Card className="promo">C</Card>);
     const root = container.firstElementChild!;
     expect(root.className).toContain('astryx-card');
-    expect(root.className).toContain('transparent');
+    expect(root.className).toContain('promo');
+  });
+
+  it('reflects variant as a theme data attribute', () => {
+    const {container} = render(<Card variant="muted">C</Card>);
+    expect(container.firstElementChild).toHaveAttribute(
+      'data-variant',
+      'muted',
+    );
+  });
+
+  it('reflects elevation as a theme data attribute', () => {
+    const {container} = render(<Card elevation="high">C</Card>);
+    expect(container.firstElementChild).toHaveAttribute(
+      'data-elevation',
+      'high',
+    );
+  });
+
+  it('defaults to the default variant at rest elevation', () => {
+    const {container} = render(<Card>C</Card>);
+    const root = container.firstElementChild!;
+    expect(root).toHaveAttribute('data-variant', 'default');
+    expect(root).toHaveAttribute('data-elevation', 'none');
   });
 
   it('applies a distinct class for each elevation level', () => {
@@ -28,18 +64,7 @@ describe('Card', () => {
       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,
-    );
+    const classes = (['none', 'low', 'med', 'high'] as const).map(classFor);
+    expect(new Set(classes).size).toBe(4);
   });
 });

package/src/Card/Card.tsx

@@ -23,13 +23,7 @@ import {
 } from '../theme/tokens.stylex';
 import {container} from '../Layout/container.stylex';
 import type {SpacingToken} from '../Layout/container.stylex';
-import {
-  paddingStyles,
-  containerPaddingInlineVarStyles,
-  containerPaddingBlockStartVarStyles,
-  containerPaddingBlockEndVarStyles,
-  spacingStepToToken,
-} from '../Layout/padding.stylex';
+import {spacingStepToToken} from '../Layout/padding.stylex';
 import type {Elevation, SizeValue, SpacingStep} from '../utils/types';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
@@ -176,14 +170,6 @@ export type {SizeValue} from '../utils/types';
 
 export interface CardProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
-  /**
-   * CSS class name(s) appended to the root element.
-   */
-  className?: string;
-  /**
-   * Inline styles to apply to the root element.
-   */
-  style?: React.CSSProperties;
   /**
    * Width of the card.
    * Numbers are treated as pixels, strings are used as-is.
@@ -217,7 +203,12 @@ export interface CardProps extends BaseProps<HTMLDivElement> {
   /**
    * Internal padding of the card using the spacing scale.
    * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
-   * @default 4 (16px)
+   *
+   * 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)
    */
   padding?: SpacingStep;
 
@@ -293,14 +284,15 @@ export function Card({
 
   // When no explicit padding prop, use theme default (set via container tokens)
   const useThemeDefault = padding == null;
-  const effectivePadding = padding ?? 4;
-  const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
+  const paddingToken = useThemeDefault
+    ? undefined
+    : (spacingStepToToken[padding] as SpacingToken);
 
   return (
     <div
       ref={ref}
       {...mergeProps(
-        themeProps('card', {variant}),
+        themeProps('card', {variant, elevation}),
         stylex.props(
           styles.card,
           variantStyles[variant],
@@ -313,7 +305,7 @@ export function Card({
             minHeight ?? null,
           ),
           ...container(
-            useThemeDefault
+            paddingToken == null
               ? {useThemeDefault: 'card'}
               : {
                   paddingInnerX: paddingToken,
@@ -322,18 +314,6 @@ export function Card({
                   paddingOuterY: paddingToken,
                 },
           ),
-          !useThemeDefault &&
-            effectivePadding !== 4 &&
-            paddingStyles[effectivePadding],
-          !useThemeDefault &&
-            effectivePadding !== 4 &&
-            containerPaddingInlineVarStyles[effectivePadding],
-          !useThemeDefault &&
-            effectivePadding !== 4 &&
-            containerPaddingBlockStartVarStyles[effectivePadding],
-          !useThemeDefault &&
-            effectivePadding !== 4 &&
-            containerPaddingBlockEndVarStyles[effectivePadding],
           // Applied after the container padding so the border-inset calc wins;
           // it reads the --container-padding-* vars set above.
           variant === 'default' && styles.withBorder,