Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(Card): add background color variants (#1213)

Cindy Zhangd5bb485d58c2
diff --git a/.gitignore b/.gitignore
index 6d53adf133..5c76c78e92 100644
--- a/.gitignore
+++ b/.gitignore
@@ -53,3 +53,4 @@ apps/sandbox/next-env.d.ts
apps/example-nextjs-tailwind/.next
.parity-test-results.json
.worktree-parity-test
+.npmrc
diff --git a/apps/storybook/stories/Card.stories.tsx b/apps/storybook/stories/Card.stories.tsx
index 991a32a787..c9480ff83f 100644
--- a/apps/storybook/stories/Card.stories.tsx
+++ b/apps/storybook/stories/Card.stories.tsx
@@ -374,35 +374,66 @@ export const OnBackgrounds: Story = {
};
/**
- * Callout card: a card with a wash section used as a callout/highlight area.
- * This pattern pairs XDSCard with a wash XDSSection for visual emphasis.
+ * Callout card: a muted card used as a callout/highlight area.
+ * Uses `variant="muted"` directly on XDSCard instead of wrapping content
+ * in a wash section β€” simpler and semantically cleaner.
*/
export const Callout: Story = {
render: () => (
<div {...stylex.props(styles.storyWrapper)}>
- <XDSCard width={350}>
- <XDSSection variant="wash">
- <XDSVStack gap={2}>
- <XDSHeading level={3}>πŸ’‘ Tip</XDSHeading>
- <p {...stylex.props(styles.text, styles.textSecondary)}>
- Use a wash section inside a card for callouts, tips, or
- highlighted information. The wash background provides visual
- contrast against the card surface.
- </p>
- </XDSVStack>
- </XDSSection>
+ <XDSCard width={350} variant="muted">
+ <XDSVStack gap={2}>
+ <XDSHeading level={3}>πŸ’‘ Tip</XDSHeading>
+ <p {...stylex.props(styles.text, styles.textSecondary)}>
+ Use <code>variant="muted"</code> for callouts, tips, or highlighted
+ information. The muted background provides visual contrast without
+ needing a nested section.
+ </p>
+ </XDSVStack>
</XDSCard>
- <XDSCard width={350}>
- <XDSSection variant="wash">
- <XDSVStack gap={2}>
- <XDSHeading level={3}>⚠️ Warning</XDSHeading>
- <p {...stylex.props(styles.text, styles.textSecondary)}>
- Callout cards work well for alerts and warnings too. The full
- bleed wash fills the card edge-to-edge.
- </p>
- </XDSVStack>
- </XDSSection>
+ <XDSCard width={350} variant="muted">
+ <XDSVStack gap={2}>
+ <XDSHeading level={3}>⚠️ Warning</XDSHeading>
+ <p {...stylex.props(styles.text, styles.textSecondary)}>
+ Muted cards work well for alerts and warnings too.
+ </p>
+ </XDSVStack>
</XDSCard>
</div>
),
};
+
+/**
+ * All background color variants in one view.
+ * `muted` uses the wash background for de-emphasised cards;
+ * the non-semantic variants use the `--color-<name>-background` token.
+ */
+export const ColorVariants: Story = {
+ render: () => (
+ <div {...stylex.props(styles.storyWrapper)}>
+ {(
+ [
+ 'default',
+ 'muted',
+ 'blue',
+ 'cyan',
+ 'gray',
+ 'green',
+ 'orange',
+ 'pink',
+ 'purple',
+ 'red',
+ 'teal',
+ 'yellow',
+ ] as const
+ ).map(variant => (
+ <div key={variant}>
+ <h4 {...stylex.props(styles.heading)}>{variant}</h4>
+ <XDSCard width={160} variant={variant}>
+ <p {...stylex.props(styles.text)}>{variant}</p>
+ </XDSCard>
+ </div>
+ ))}
+ </div>
+ ),
+};
diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjs
index 9888aa73ce..43eff87b5f 100644
--- a/packages/core/src/Card/Card.doc.mjs
+++ b/packages/core/src/Card/Card.doc.mjs
@@ -10,6 +10,7 @@ export const docs = {
'Sets CSS variables for child layout components',
'Supports `padding={0}` for edge-to-edge content',
'Composable with XDSLayout, XDSCollapsible, and XDSCollapsibleGroup',
+ 'Background color variants: default, muted, and 10 non-semantic palette colors',
],
props: [
{
@@ -43,6 +44,13 @@ export const docs = {
description: 'Internal padding using the spacing scale.',
default: '4',
},
+ {
+ name: 'variant',
+ type: "'default' | 'muted' | 'blue' | 'cyan' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'",
+ description:
+ 'Background color variant. `default` uses the standard card background. `muted` uses the wash background for de-emphasised cards. The non-semantic variants use the corresponding `--color-<name>-background` token.',
+ default: "'default'",
+ },
],
examples: [
{
@@ -59,6 +67,18 @@ export const docs = {
label: 'Simple content',
code: `<XDSCard>
<p>Card content with default padding</p>
+</XDSCard>`,
+ },
+ {
+ label: 'Muted background',
+ code: `<XDSCard variant="muted" width={300}>
+ <p>De-emphasised card with wash background</p>
+</XDSCard>`,
+ },
+ {
+ label: 'Color variant',
+ code: `<XDSCard variant="blue" width={300}>
+ <p>Blue tinted card</p>
</XDSCard>`,
},
{
diff --git a/packages/core/src/Card/XDSCard.tsx b/packages/core/src/Card/XDSCard.tsx
index 3d668cd027..3c39da9384 100644
--- a/packages/core/src/Card/XDSCard.tsx
+++ b/packages/core/src/Card/XDSCard.tsx
@@ -28,19 +28,50 @@ import type {SizeValue, SpacingStep} from '../utils/types';
import {xdsClassName, mergeProps} from '../utils';
import type {XDSBaseProps} from '../XDSBaseProps';
+// =============================================================================
+// Variant type
+// =============================================================================
+
+/**
+ * Background color variant for XDSCard.
+ * - `default`: the standard card background (`--color-background-card`)
+ * - `muted`: subtle muted background (`--color-background-muted`) for de-emphasised cards
+ * - Non-semantic palette: `blue | cyan | gray | green | orange | pink | purple | red | teal | yellow`
+ * Each uses the corresponding `--color-background-<name>` token (20% opacity tint).
+ *
+ * Non-default variants have no border β€” the background provides its own visual separation.
+ */
+export type XDSCardVariant =
+ | 'default'
+ | 'muted'
+ | 'blue'
+ | 'cyan'
+ | 'gray'
+ | 'green'
+ | 'orange'
+ | 'pink'
+ | 'purple'
+ | 'red'
+ | 'teal'
+ | 'yellow';
+
+// =============================================================================
+// Styles
+// =============================================================================
+
const styles = stylex.create({
// Outer wrapper: visual styling with clip for border-radius
cardOuter: {
'--card-radius': radiusVars['--radius-container'],
- backgroundColor: colorVars['--color-background-card'],
borderRadius: 'var(--card-radius)',
- // No drop-shadow β€” matches WWW XDSCard which uses border only
overflow: 'clip',
+ },
+ // Border only for the default variant
+ withBorder: {
borderWidth: borderVars['--border-width'],
borderStyle: 'solid',
borderColor: colorVars['--color-border-emphasized'],
},
-
// Inner wrapper: container padding and overflow handling
cardInner: {
height: '100%',
@@ -51,6 +82,46 @@ const styles = stylex.create({
},
});
+// Background variant styles β€” each maps to a design token
+const variantStyles = stylex.create({
+ default: {
+ backgroundColor: colorVars['--color-background-card'],
+ },
+ muted: {
+ backgroundColor: colorVars['--color-background-muted'],
+ },
+ blue: {
+ backgroundColor: colorVars['--color-background-blue'],
+ },
+ cyan: {
+ backgroundColor: colorVars['--color-background-cyan'],
+ },
+ gray: {
+ backgroundColor: colorVars['--color-background-gray'],
+ },
+ green: {
+ backgroundColor: colorVars['--color-background-green'],
+ },
+ orange: {
+ backgroundColor: colorVars['--color-background-orange'],
+ },
+ pink: {
+ backgroundColor: colorVars['--color-background-pink'],
+ },
+ purple: {
+ backgroundColor: colorVars['--color-background-purple'],
+ },
+ red: {
+ backgroundColor: colorVars['--color-background-red'],
+ },
+ teal: {
+ backgroundColor: colorVars['--color-background-teal'],
+ },
+ yellow: {
+ backgroundColor: colorVars['--color-background-yellow'],
+ },
+});
+
// Dynamic styles for sizing props
const dynamicStyles = stylex.create({
sizing: (
@@ -114,6 +185,15 @@ export interface XDSCardProps extends XDSBaseProps<HTMLDivElement> {
* @default 4 (16px)
*/
padding?: SpacingStep;
+
+ /**
+ * Background color variant.
+ * - `default`: standard card background with border
+ * - `muted`: subtle muted background for de-emphasised cards (no border)
+ * - Non-semantic: `blue`, `cyan`, `gray`, `green`, `orange`, `pink`, `purple`, `red`, `teal`, `yellow` (no border)
+ * @default 'default'
+ */
+ variant?: XDSCardVariant;
}
/**
@@ -135,6 +215,20 @@ export interface XDSCardProps extends XDSBaseProps<HTMLDivElement> {
* />
* </XDSCard>
* ```
+ *
+ * @example
+ * ```
+ * <XDSCard variant="blue" width={300}>
+ * <p>Blue tinted card</p>
+ * </XDSCard>
+ * ```
+ *
+ * @example
+ * ```
+ * <XDSCard variant="muted" width={300}>
+ * <p>Subtle de-emphasised card</p>
+ * </XDSCard>
+ * ```
*/
export function XDSCard({
width,
@@ -143,6 +237,7 @@ export function XDSCard({
minHeight,
children,
padding,
+ variant = 'default',
xstyle,
className,
style,
@@ -161,9 +256,11 @@ export function XDSCard({
<div
ref={ref}
{...mergeProps(
- xdsClassName('card'),
+ xdsClassName('card', {variant}),
stylex.props(
styles.cardOuter,
+ variantStyles[variant],
+ variant === 'default' && styles.withBorder,
dynamicStyles.sizing(
width ?? null,
height ?? null,
diff --git a/packages/core/src/Card/index.ts b/packages/core/src/Card/index.ts
index c9d23b6a82..c9bbce07e8 100644
--- a/packages/core/src/Card/index.ts
+++ b/packages/core/src/Card/index.ts
@@ -10,4 +10,4 @@
*/
export {XDSCard} from './XDSCard';
-export type {XDSCardProps, SizeValue} from './XDSCard';
+export type {XDSCardProps, XDSCardVariant, SizeValue} from './XDSCard';