An open source design system that's fully customizable and agent ready
TypeScript
fix(Card): reflect elevation as a theme target, correct the padding default docs (#5491)
Cindy Zhangcac77bcd9634
diff --git a/.changeset/card-nightly-audit-20260825.md b/.changeset/card-nightly-audit-20260825.mdnew file mode 100644index 0000000000..4dd725927d--- /dev/null+++ b/.changeset/card-nightly-audit-20260825.md@@ -0,0 +1,11 @@+---+'@astryxdesign/core': patch+---++[fix] Card: reflect `elevation` as a theme target so a theme can reach it, and correct the documented `padding` default++`elevation` picked a style object but never reached the DOM, so `astryx-card` exposed `data-variant` and nothing for elevation and a theme could not style the four shadow tiers. It now rides `themeProps` alongside `variant`.++The `padding` prop documented `4` as its default. With the prop omitted the card reads the theme's card padding, and most shipped themes set that to a different step, so writing the documented default explicitly changed the card's size. The prop docs, the JSDoc and the playground default now say that omitting the prop takes the theme's padding and passing a step overrides it. The four `effectivePadding !== 4` style branches that encoded the same wrong default in code are gone: `container()` already sets every variable they set, verified identical across all eleven padding steps on both a bordered and a borderless card.++@cixzhangdiff --git a/.github/a11y-baseline.json b/.github/a11y-baseline.jsonindex 3e27d35432..705f2fef8e 100644--- a/.github/a11y-baseline.json+++ b/.github/a11y-baseline.json@@ -13,46 +13,6 @@"impact": "serious","helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"},- {- "key": "Card::Callout::color-contrast",- "impact": "serious",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"- },- {- "key": "Card::Color Variants::color-contrast",- "impact": "serious",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"- },- {- "key": "Card::Elevations::color-contrast",- "impact": "serious",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"- },- {- "key": "Card::Full Bleed::color-contrast",- "impact": "serious",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"- },- {- "key": "Card::Mixed Content::color-contrast",- "impact": "serious",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"- },- {- "key": "Card::On Backgrounds::color-contrast",- "impact": "serious",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"- },- {- "key": "Card::Single Section::color-contrast",- "impact": "serious",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"- },- {- "key": "Card::Sizes::color-contrast",- "impact": "serious",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"- },{"key": "Carousel::Card Content::color-contrast","impact": "serious",diff --git a/apps/storybook/stories/Card.stories.tsx b/apps/storybook/stories/Card.stories.tsxindex 2956821ccb..7614f6febd 100644--- a/apps/storybook/stories/Card.stories.tsx+++ b/apps/storybook/stories/Card.stories.tsx@@ -45,6 +45,9 @@ const styles = stylex.create({fontSize: 14,color: colorVars['--color-text-secondary'],},+ narrowContainer: {+ width: 320,+ },});const meta: Meta<typeof Card> = {@@ -466,3 +469,67 @@ export const ColorVariants: Story = {</div>),};++/**+ * A card with no children, and one with a minimum height. An empty card holds+ * its padding and radius rather than collapsing, so a placeholder or a loading+ * shell keeps the surrounding layout stable.+ */+export const Empty: Story = {+ render: () => (+ <div {...stylex.props(styles.storyWrapper)}>+ <div>+ <h4 {...stylex.props(styles.heading)}>No children</h4>+ <Card width={250} />+ </div>+ <div>+ <h4 {...stylex.props(styles.heading)}>No children, minHeight 120</h4>+ <Card width={250} minHeight={120} />+ </div>+ </div>+ ),+};++/**+ * Long prose and a title long enough to wrap, in a fixed-width card. Text wraps+ * and the card grows to fit. Most languages run longer than English, so this is+ * the state translated copy lands in.+ */+export const LongContent: Story = {+ render: () => (+ <div {...stylex.props(styles.storyWrapper)}>+ <Card width={280}>+ <VStack gap={2}>+ <Heading level={3}>+ A card title long enough to wrap onto several lines+ </Heading>+ <p {...stylex.props(styles.text)}>+ Cards grow to fit their content, so a long description keeps+ wrapping rather than being cut off. Sibling cards in a grid stay+ aligned on their top edge and the tallest one sets the row height.+ </p>+ </VStack>+ </Card>+ </div>+ ),+};++/**+ * A card with no width prop inside a 320px container: the width comes from the+ * parent, so the card reflows to the container instead of forcing horizontal+ * scroll on a narrow screen.+ */+export const NarrowContainer: Story = {+ render: () => (+ <div {...stylex.props(styles.narrowContainer)}>+ <Card>+ <VStack gap={2}>+ <Heading level={3}>Narrow container</Heading>+ <p {...stylex.props(styles.text)}>+ The card fills the container it is given.+ </p>+ </VStack>+ </Card>+ </div>+ ),+};diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjsindex 6b4c9773a1..3f24581bb3 100644--- a/packages/core/src/Card/Card.doc.mjs+++ b/packages/core/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.',},diff --git a/packages/core/src/Card/Card.test.tsx b/packages/core/src/Card/Card.test.tsxindex e7b3601d40..1e351004ed 100644--- a/packages/core/src/Card/Card.test.tsx+++ b/packages/core/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);});});diff --git a/packages/core/src/Card/Card.tsx b/packages/core/src/Card/Card.tsxindex e35ce8c1d2..3d8094fa46 100644--- a/packages/core/src/Card/Card.tsx+++ b/packages/core/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 (<divref={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,