Skip to content

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

TypeScript

fix(Card): let a card yield to its flex row or grid track (#6813)

David Petersen1bbbf636b0f0
diff --git a/.changeset/card-yields-to-track.md b/.changeset/card-yields-to-track.md
new file mode 100644
index 0000000000..f1e25edd6c
--- /dev/null
+++ b/.changeset/card-yields-to-track.md
@@ -0,0 +1,16 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Card: yield to a flex row or grid track instead of widening it to the card's content.
+
+A card no longer holds its row or `1fr` grid track at its min-content width,
+so a long unbroken value (an ID, a hash) inside a card can no longer push
+side-by-side cards past a phone screen. Cards that fit are unchanged. Content
+that cannot wrap is clipped at the card edge, as it already was for cards with
+an explicit `width`; truncate such values with `Text maxLines={1}` and give wide
+content its own scroll region. An explicit `width` is now the card's preferred
+width in a row rather than a floor. To hold it, wrap the card in `StackItem` in
+a flex row, or set a consumer `minWidth` on the Card in Grid.
+
+@thedjpetersen
diff --git a/apps/storybook/stories/Card.stories.tsx b/apps/storybook/stories/Card.stories.tsx
index 42f1936b3e..64126523c8 100644
--- a/apps/storybook/stories/Card.stories.tsx
+++ b/apps/storybook/stories/Card.stories.tsx
@@ -1,5 +1,6 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+import type {ReactNode} from 'react';
import type {Meta, StoryObj} from '@storybook/react';
import * as stylex from '@stylexjs/stylex';
import {Card} from '@astryxdesign/core/Card';
@@ -14,7 +15,8 @@ import {
LayoutFooter,
} from '@astryxdesign/core/Layout';
import {Button} from '@astryxdesign/core/Button';
-import {Heading} from '@astryxdesign/core/Text';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {Grid} from '@astryxdesign/core/Grid';
import {Theme, defineTheme} from '@astryxdesign/core/theme';
import {
colorVars,
@@ -54,6 +56,19 @@ const styles = stylex.create({
narrowContainer: {
width: 320,
},
+ frames: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-6'],
+ },
+ frame: {
+ borderWidth: 1,
+ borderStyle: 'dashed',
+ borderColor: colorVars['--color-border'],
+ borderRadius: 8,
+ },
+ frame320: {width: 320},
+ frame390: {width: 390},
});
const meta: Meta<typeof Card> = {
@@ -617,3 +632,110 @@ export const NarrowContainer: Story = {
</div>
),
};
+
+const payouts = [
+ {label: 'Payout', amount: '$1,240.00', id: 'po_1Q8ZK4X7M2N5P3R6T9V1W4YB'},
+ {label: 'Refund', amount: '-$86.50', id: 're_3NfK9Lm2Qx7Vb4Tz8Rw1Hy6C'},
+ {label: 'Adjustment', amount: '$12.00', id: 'adj_7Hq2Wm9Kx4Lz8Vn3Rb6Tf1PD'},
+];
+
+function PayoutCard({
+ payout,
+ truncateId,
+}: {
+ payout: (typeof payouts)[number];
+ truncateId?: boolean;
+}) {
+ return (
+ <Card>
+ <VStack gap={1}>
+ <Heading level={3}>{payout.label}</Heading>
+ <Text hasTabularNumbers>{payout.amount}</Text>
+ <Text type="supporting" maxLines={truncateId ? 1 : undefined}>
+ {payout.id}
+ </Text>
+ </VStack>
+ </Card>
+ );
+}
+
+function RowFrame({
+ label,
+ width,
+ children,
+}: {
+ label: string;
+ width?: 320 | 390;
+ children: ReactNode;
+}) {
+ return (
+ <div>
+ <p {...stylex.props(styles.heading)}>{label}</p>
+ <div
+ {...stylex.props(
+ styles.frame,
+ width === 320 && styles.frame320,
+ width === 390 && styles.frame390,
+ )}>
+ {children}
+ </div>
+ </div>
+ );
+}
+
+/**
+ * Three cards sharing a row in 320px and 390px frames and at full width.
+ * Each card shrinks to its HStack share or Grid track instead of widening
+ * the row to fit its longest unbroken value, so the row stays inside the
+ * frame. A value that cannot wrap is clipped at the card edge (the raw IDs
+ * in the first two frames); the Grid frames truncate it with
+ * `maxLines={1}`, the recommended form, which shows the full value in a
+ * tooltip.
+ */
+export const InNarrowRow: Story = {
+ render: () => (
+ <div {...stylex.props(styles.frames)}>
+ <RowFrame
+ label="HStack, 390px frame, raw IDs (clipped at the card edge)"
+ width={390}>
+ <HStack gap={3}>
+ {payouts.map(payout => (
+ <PayoutCard key={payout.id} payout={payout} />
+ ))}
+ </HStack>
+ </RowFrame>
+ <RowFrame label="HStack, 320px frame, raw IDs" width={320}>
+ <HStack gap={3}>
+ {payouts.map(payout => (
+ <PayoutCard key={payout.id} payout={payout} />
+ ))}
+ </HStack>
+ </RowFrame>
+ <RowFrame
+ label="Grid columns={3}, 390px frame, IDs truncated with maxLines={1}"
+ width={390}>
+ <Grid columns={3} gap={3}>
+ {payouts.map(payout => (
+ <PayoutCard key={payout.id} payout={payout} truncateId />
+ ))}
+ </Grid>
+ </RowFrame>
+ <RowFrame
+ label="Grid columns={3}, 320px frame, IDs truncated"
+ width={320}>
+ <Grid columns={3} gap={3}>
+ {payouts.map(payout => (
+ <PayoutCard key={payout.id} payout={payout} truncateId />
+ ))}
+ </Grid>
+ </RowFrame>
+ <RowFrame label="Grid columns={3}, full width (unchanged)">
+ <Grid columns={3} gap={3}>
+ {payouts.map(payout => (
+ <PayoutCard key={payout.id} payout={payout} truncateId />
+ ))}
+ </Grid>
+ </RowFrame>
+ </div>
+ ),
+};
diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjs
index 3f24581bb3..247552e656 100644
--- a/packages/core/src/Card/Card.doc.mjs
+++ b/packages/core/src/Card/Card.doc.mjs
@@ -17,6 +17,7 @@ export const docs = {
{guidance: true, description: 'Spacing and alignment alone create visual grouping. Not everything needs a container; try removing the card and see if the grouping is still clear from whitespace and typography.'},
{guidance: true, description: 'Keep padding consistent across sibling cards so they align visually in a grid or list.'},
{guidance: true, description: 'Pair a card with Layout when you need a structured header, scrollable content, and footer with actions.'},
+ {guidance: true, description: 'Let cards share a row or grid on a phone: a card shrinks to fit its track and clips content that cannot wrap at its edge. Truncate long IDs, hashes, and URLs with Text maxLines={1} (the full value shows in a tooltip), and give wide content its own scroll region: Table scrolls by itself; put code or other wide content in a ScrollableArea.'},
{guidance: false, description: 'Default to cards for visual grouping. A heading + Stack with proper spacing creates hierarchy without adding borders everywhere. Cards should be the exception, not the default.'},
{guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups: these are page regions, use Section or heading + stack.'},
{guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.'},
@@ -32,7 +33,7 @@ export const docs = {
{
name: 'width',
type: 'SizeValue',
- description: 'Width of the card (number = pixels, string = used as-is).',
+ description: 'Width of the card (number = pixels, string = used as-is). In a flex row or grid track this is the preferred width: the card shrinks below it when the row is narrower. To hold the width in a flex row, wrap the card in StackItem (static by default) and let the row wrap or scroll. In Grid, set a consumer minWidth on the Card and size the track accordingly.',
},
{
name: 'height',
@@ -76,6 +77,46 @@ export const docs = {
default: "'none'",
},
],
+ examples: [
+ {
+ label: 'Cards sharing a row on a phone, with long IDs',
+ code: `
+import {Card} from '@astryxdesign/core/Card';
+import {Grid} from '@astryxdesign/core/Grid';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Heading} from '@astryxdesign/core/Heading';
+import {Text} from '@astryxdesign/core/Text';
+
+const payouts = [
+ {label: 'Payout', amount: '$1,240.00', id: 'po_1Q8ZK4X7M2N5P3R6T9V1W4YB'},
+ {label: 'Refund', amount: '-$86.50', id: 're_3NfK9Lm2Qx7Vb4Tz8Rw1Hy6C'},
+ {label: 'Adjustment', amount: '$12.00', id: 'adj_7Hq2Wm9Kx4Lz8Vn3Rb6Tf1PD'},
+];
+
+// Each card takes one grid track and shrinks with it, so three cards fit a
+// 390px phone without widening the page. The ID cannot wrap, so it truncates
+// with maxLines={1} (the full value shows in a tooltip) instead of running
+// past the card edge.
+function PayoutCards() {
+ return (
+ <Grid columns={3} gap={3}>
+ {payouts.map(payout => (
+ <Card key={payout.id}>
+ <VStack gap={1}>
+ <Heading level={3}>{payout.label}</Heading>
+ <Text hasTabularNumbers>{payout.amount}</Text>
+ <Text type="supporting" maxLines={1}>
+ {payout.id}
+ </Text>
+ </VStack>
+ </Card>
+ ))}
+ </Grid>
+ );
+}
+`,
+ },
+ ],
playground: {
defaults: {
children: {
@@ -118,6 +159,7 @@ export const docsZh = {
{guidance: true, description: 'Spacing and alignment alone create visual grouping. Not everything needs a container; try removing the card and see if the grouping is still clear from whitespace and typography.'},
{guidance: true, description: 'Keep padding consistent across sibling cards so they align visually in a grid or list.'},
{guidance: true, description: 'Pair a card with Layout when you need a structured header, scrollable content, and footer with actions.'},
+ {guidance: true, description: 'Let cards share a row or grid on a phone: a card shrinks to fit its track and clips content that cannot wrap at its edge. Truncate long IDs, hashes, and URLs with Text maxLines={1} (the full value shows in a tooltip), and give wide content its own scroll region: Table scrolls by itself; put code or other wide content in a ScrollableArea.'},
{guidance: false, description: 'Default to cards for visual grouping. A heading + Stack with proper spacing creates hierarchy without adding borders everywhere. Cards should be the exception, not the default.'},
{guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups: these are page regions, use Section or heading + stack.'},
{guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.'},
@@ -168,6 +210,7 @@ export const docsDense = {
{guidance: true, description: 'Spacing + alignment alone create visual grouping. Not everything needs a container; try removing the card; if grouping still reads from whitespace + typography, skip it.'},
{guidance: true, description: 'Keep padding consistent across sibling cards so they align visually in a grid or list.'},
{guidance: true, description: 'Pair a card w/ Layout when you need a structured header, scrollable content, and footer with actions.'},
+ {guidance: true, description: 'Card shrinks to its row/grid track, clips unwrappable content at its edge. Long IDs/hashes/URLs → Text maxLines={1} (tooltip shows full value). Wide content → own scroll region (Table scrolls itself; ScrollableArea otherwise).'},
{guidance: false, description: 'Default to cards for grouping. Heading + Stack w/ proper spacing creates hierarchy w/o borders everywhere. Cards are the exception, not the default.'},
{guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups are page regions; use Section or heading + stack.'},
{guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.'},
diff --git a/packages/core/src/Card/Card.test.tsx b/packages/core/src/Card/Card.test.tsx
index 8338725cfc..435b94e3d6 100644
--- a/packages/core/src/Card/Card.test.tsx
+++ b/packages/core/src/Card/Card.test.tsx
@@ -3,6 +3,7 @@
import {createRef} from 'react';
import {describe, it, expect} from 'vitest';
import {render} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
import {Card} from './Card';
import type {CardVariant} from './Card';
@@ -12,6 +13,68 @@ describe('Card', () => {
expect(getByText('Hello')).toBeInTheDocument();
});
+ describe('in a flex row or grid track', () => {
+ it('yields to its track instead of holding it at its min-content width', () => {
+ const {getByTestId} = render(<Card data-testid="card">C</Card>);
+ // Without this, `overflow: clip` keeps the automatic minimum size, so a
+ // long unbroken value widens the row or a `1fr` track past its parent.
+ expect(getComputedStyle(getByTestId('card')).minWidth).toBe('0');
+ });
+
+ it('clips rather than scrolls, so it never becomes a scroll container', () => {
+ const {getByTestId} = render(<Card data-testid="card">C</Card>);
+ const style = getComputedStyle(getByTestId('card'));
+ // A scroll container would capture sticky descendants and become an
+ // unnamed keyboard tab stop whenever its content overflows.
+ expect(style.overflow).toBe('clip');
+ expect(style.overflowX).not.toBe('auto');
+ });
+
+ it('yields the same way for every variant and elevation', () => {
+ const {getByTestId} = render(
+ <>
+ <Card data-testid="muted" variant="muted" elevation="high">
+ C
+ </Card>
+ <Card data-testid="transparent" variant="transparent">
+ C
+ </Card>
+ </>,
+ );
+ expect(getComputedStyle(getByTestId('muted')).minWidth).toBe('0');
+ expect(getComputedStyle(getByTestId('transparent')).minWidth).toBe('0');
+ });
+
+ it('still scrolls a fixed-height card and lets it yield', () => {
+ const {getByTestId} = render(
+ <Card data-testid="card" height={200}>
+ C
+ </Card>,
+ );
+ const style = getComputedStyle(getByTestId('card'));
+ expect(style.overflow).toBe('auto');
+ expect(style.minWidth).toBe('0');
+ });
+
+ it('keeps width as the preferred size and lets a consumer minimum win', () => {
+ const overrides = stylex.create({hold: {minWidth: 240}});
+ const {getByTestId} = render(
+ <>
+ <Card data-testid="sized" width={320}>
+ C
+ </Card>
+ <Card data-testid="held" width={320} xstyle={overrides.hold}>
+ C
+ </Card>
+ </>,
+ );
+ // An explicit width does not become a floor: in a narrow row the card
+ // still yields, and a consumer minimum is the way to hold it.
+ expect(getComputedStyle(getByTestId('sized')).minWidth).toBe('0');
+ expect(getComputedStyle(getByTestId('held')).minWidth).toBe('240px');
+ });
+ });
+
it('forwards ref to the rendered element', () => {
const ref = createRef<HTMLDivElement>();
const {container} = render(<Card ref={ref}>C</Card>);
diff --git a/packages/core/src/Card/Card.tsx b/packages/core/src/Card/Card.tsx
index 83f870c8ea..52f4f3f833 100644
--- a/packages/core/src/Card/Card.tsx
+++ b/packages/core/src/Card/Card.tsx
@@ -60,6 +60,16 @@ const styles = stylex.create({
card: {
'--_card-radius': radiusVars['--radius-container'],
borderRadius: 'var(--_card-radius)',
+ // A card in a flex row or grid cell yields to its track instead of
+ // holding it at the card's min-content width (a long ID or a nowrap row
+ // inside used to widen `1fr` tracks and overflow phone rows).
+ minWidth: 0,
+ // Clip, not scroll: `overflow-x: auto` would make every card a scroll
+ // container, so sticky descendants would stick to the card instead of
+ // the page, and an overflowing card would become an unnamed keyboard tab
+ // stop. Content that cannot wrap is clipped at the card edge; long
+ // values truncate (Text maxLines) and wide content brings its own scroll
+ // region (Table, ScrollableArea).
overflow: 'clip',
// Resting elevation is set via --_card-elevation (see elevationStyles).
// The shadow list also reads --_card-ring so composing surfaces — e.g.