An open source design system that's fully customizable and agent ready
TypeScript
feat(core): add elevation prop to configurable surfaces (#4251)
Kenton Quatman9caa99e8282f
diff --git a/.changeset/elevation-prop-configurable-surfaces.md b/.changeset/elevation-prop-configurable-surfaces.mdnew file mode 100644index 0000000000..2bd2bd0ab6--- /dev/null+++ b/.changeset/elevation-prop-configurable-surfaces.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[feat] Add an `elevation` prop to configurable surfaces — Card, ClickableCard, SelectableCard, Button, IconButton, ButtonGroup, Thumbnail, and Banner take the full `'none' | 'low' | 'med' | 'high'` scale; ChatComposer takes `'none' | 'low'`. Defaults preserve today's appearance (`none` everywhere except ChatComposer's `low`), so nothing changes unless you opt in. (#4146)++@kentonquatmandiff --git a/apps/storybook/stories/Banner.stories.tsx b/apps/storybook/stories/Banner.stories.tsxindex a1a0ec181a..e8fb605151 100644--- a/apps/storybook/stories/Banner.stories.tsx+++ b/apps/storybook/stories/Banner.stories.tsx@@ -21,6 +21,11 @@ const meta: Meta<typeof Banner> = {options: ['card', 'section'],description: 'Container type',},+ elevation: {+ control: 'inline-radio',+ options: ['none', 'low', 'med', 'high'],+ description: 'Resting shadow depth (for a floating banner)',+ },isDismissable: {control: 'boolean',description:@@ -65,6 +70,15 @@ export const Success: Story = {},};+export const Floating: Story = {+ args: {+ status: 'info',+ title: 'This banner floats above content.',+ description: 'A raised banner draws attention as an overlay.',+ elevation: 'med',+ },+};+export const WithDescription: Story = {args: {status: 'info',@@ -229,9 +243,7 @@ export const AllFeatures: Story = {<Bannerstatus="info"title="With action button"- endContent={- <Button label="Learn more" variant="secondary" size="sm" />- }+ endContent={<Button label="Learn more" variant="secondary" size="sm" />}/><Bannerstatus="error"diff --git a/apps/storybook/stories/Button.stories.tsx b/apps/storybook/stories/Button.stories.tsxindex 63b9ab7e46..3e2114c853 100644--- a/apps/storybook/stories/Button.stories.tsx+++ b/apps/storybook/stories/Button.stories.tsx@@ -31,6 +31,11 @@ const meta: Meta<typeof Button> = {options: ['sm', 'md', 'lg'],description: 'Size variant',},+ elevation: {+ control: 'inline-radio',+ options: ['none', 'low', 'med', 'high'],+ description: 'Resting shadow depth (for floating buttons / FABs)',+ },isLoading: {control: 'boolean',description: 'Loading state',@@ -353,3 +358,18 @@ export const Truncation: Story = {</div>),};++export const Elevations: Story = {+ render: () => (+ <div style={{display: 'flex', gap: 24, alignItems: 'center'}}>+ {(['none', 'low', 'med', 'high'] as const).map(elevation => (+ <div key={elevation} style={{textAlign: 'center'}}>+ <p style={{fontSize: 12, color: '#666', marginBottom: 8}}>+ elevation="{elevation}"+ </p>+ <Button label={elevation} variant="primary" elevation={elevation} />+ </div>+ ))}+ </div>+ ),+};diff --git a/apps/storybook/stories/ButtonGroup.stories.tsx b/apps/storybook/stories/ButtonGroup.stories.tsxindex dfc90f1280..81fb0ccdb3 100644--- a/apps/storybook/stories/ButtonGroup.stories.tsx+++ b/apps/storybook/stories/ButtonGroup.stories.tsx@@ -25,6 +25,10 @@ const meta: Meta<typeof ButtonGroup> = {argTypes: {orientation: {control: 'select', options: ['horizontal', 'vertical']},size: {control: 'select', options: ['sm', 'md', 'lg']},+ elevation: {+ control: 'inline-radio',+ options: ['none', 'low', 'med', 'high'],+ },},};diff --git a/apps/storybook/stories/Card.stories.tsx b/apps/storybook/stories/Card.stories.tsxindex 571bd693d0..2956821ccb 100644--- a/apps/storybook/stories/Card.stories.tsx+++ b/apps/storybook/stories/Card.stories.tsx@@ -75,6 +75,11 @@ const meta: Meta<typeof Card> = {control: {type: 'range', min: 100, max: 600, step: 10},description: 'Minimum height in pixels',},+ elevation: {+ control: {type: 'inline-radio'},+ options: ['none', 'low', 'med', 'high'],+ description: 'Resting shadow depth',+ },},};@@ -109,6 +114,28 @@ export const WithSimpleContent: Story = {),};+export const Elevations: Story = {+ render: () => (+ <div {...stylex.props(styles.storyWrapper)}>+ {(['none', 'low', 'med', 'high'] as const).map(elevation => (+ <VStack key={elevation} gap={2}>+ <p {...stylex.props(styles.heading)}>+ elevation="{elevation}"+ </p>+ <Card width={220} elevation={elevation}>+ <VStack gap={1}>+ <Heading level={3}>{elevation}</Heading>+ <p {...stylex.props(styles.text, styles.textSecondary)}>+ Resting at the {elevation} shadow level.+ </p>+ </VStack>+ </Card>+ </VStack>+ ))}+ </div>+ ),+};+export const WithInnerLayout: Story = {render: () => (<Card width={350}>@@ -121,8 +148,8 @@ export const WithInnerLayout: Story = {content={<LayoutContent><p {...stylex.props(styles.text, styles.textSecondary)}>- When using Layout, the layout uses negative margin to escape- the container padding, then manages its own padding.+ When using Layout, the layout uses negative margin to escape the+ container padding, then manages its own padding.</p></LayoutContent>}diff --git a/apps/storybook/stories/ChatComposer.stories.tsx b/apps/storybook/stories/ChatComposer.stories.tsxindex 959de029ae..604fab7017 100644--- a/apps/storybook/stories/ChatComposer.stories.tsx+++ b/apps/storybook/stories/ChatComposer.stories.tsx@@ -361,9 +361,7 @@ export const Feedback: Story = {<div style={{width: '100%'}}><List><ListItem- label={- <Text weight="bold">Do you want to proceed?</Text>- }+ label={<Text weight="bold">Do you want to proceed?</Text>}/>{options.map(opt => (<ListItem@@ -387,3 +385,18 @@ export const Feedback: Story = {);},};++/**+ * Flat composer — `elevation="none"` drops the resting shadow so depth comes+ * from the border and focus ring instead. The default is `low` (raised).+ */+export const Flat: Story = {+ render: () => (+ <ChatComposer+ elevation="none"+ onSubmit={value => {+ console.log('Submit:', value);+ }}+ />+ ),+};diff --git a/apps/storybook/stories/ClickableCard.stories.tsx b/apps/storybook/stories/ClickableCard.stories.tsxindex b6da2d39ef..547ef16ef7 100644--- a/apps/storybook/stories/ClickableCard.stories.tsx+++ b/apps/storybook/stories/ClickableCard.stories.tsx@@ -29,6 +29,10 @@ const meta: Meta<typeof ClickableCard> = {'yellow',],},+ elevation: {+ control: 'inline-radio',+ options: ['none', 'low', 'med', 'high'],+ },},parameters: {docs: {diff --git a/apps/storybook/stories/IconButton.stories.tsx b/apps/storybook/stories/IconButton.stories.tsxindex d8763f502c..debefbbe3a 100644--- a/apps/storybook/stories/IconButton.stories.tsx+++ b/apps/storybook/stories/IconButton.stories.tsx@@ -31,6 +31,11 @@ const meta: Meta<typeof IconButton> = {options: ['sm', 'md', 'lg'],description: 'Size variant',},+ elevation: {+ control: 'inline-radio',+ options: ['none', 'low', 'med', 'high'],+ description: 'Resting shadow depth (raise for a FAB)',+ },isLoading: {control: 'boolean',description: 'Loading state',diff --git a/apps/storybook/stories/SelectableCard.stories.tsx b/apps/storybook/stories/SelectableCard.stories.tsxindex d60ade0260..f8c377420d 100644--- a/apps/storybook/stories/SelectableCard.stories.tsx+++ b/apps/storybook/stories/SelectableCard.stories.tsx@@ -29,6 +29,10 @@ const meta: Meta<typeof SelectableCard> = {'yellow',],},+ elevation: {+ control: 'inline-radio',+ options: ['none', 'low', 'med', 'high'],+ },},parameters: {docs: {diff --git a/apps/storybook/stories/Thumbnail.stories.tsx b/apps/storybook/stories/Thumbnail.stories.tsxindex 3b94f60a83..c3a2a53bde 100644--- a/apps/storybook/stories/Thumbnail.stories.tsx+++ b/apps/storybook/stories/Thumbnail.stories.tsx@@ -25,6 +25,11 @@ const meta: Meta<typeof Thumbnail> = {control: 'boolean',description: 'Whether the thumbnail is disabled',},+ elevation: {+ control: 'inline-radio',+ options: ['none', 'low', 'med', 'high'],+ description: 'Resting shadow depth',+ },},};@@ -132,9 +137,7 @@ export const Placeholder: Story = {</p>);}- return (- <Thumbnail label="report.pdf" onRemove={() => setVisible(false)} />- );+ return <Thumbnail label="report.pdf" onRemove={() => setVisible(false)} />;},};diff --git a/packages/cli/docs/elevation.doc.mjs b/packages/cli/docs/elevation.doc.mjsindex 7f655e714e..767d5b8945 100644--- a/packages/cli/docs/elevation.doc.mjs+++ b/packages/cli/docs/elevation.doc.mjs@@ -36,10 +36,85 @@ export const docs = {},],},+ {+ title: 'Choosing a level',+ category: 'foundations',+ content: [+ {+ type: 'prose',+ text: 'Pick the level by how far the surface sits from the page, not by how much shadow you want. Elevation encodes stacking order: a higher level means the surface is layered over more of the UI. Use exactly one level per surface, and only raise a surface above `none` when it actually sits above other content.',+ },+ {+ type: 'table',+ headers: ['Level', 'When to use', 'Examples'],+ rows: [+ [+ 'none',+ 'The component is flat and embedded in the surface — it is part of the page, not layered above it. This is the default for every surface except ChatComposer.',+ 'A Card in a grid, an inline Banner, a standard Button',+ ],+ [+ 'low',+ 'The component is in the normal page flow but should read as distinct from the background. Use for emphasis or to separate the component from the surface behind it — the component still sits on the page, it is not floating over other content.',+ 'A raised Card that needs emphasis, a ChatComposer, a resting Thumbnail',+ ],+ [+ 'med',+ 'The component sits over other content on the same page — it floats above nearby elements but not the whole screen.',+ 'A Popover, a floating Banner, a floating action Button',+ ],+ [+ 'high',+ 'The component is placed over the entire UI — it is the topmost layer and typically has a backdrop or takes focus from everything else.',+ 'A modal Dialog, a full-screen overlay surface',+ ],+ ],+ },+ {+ type: 'prose',+ text: 'If two surfaces overlap, the one on top takes the higher level. If a surface does not overlap anything, it is `none` or `low` — never `med` or `high`.',+ },+ ],+ },+ {+ title: 'The elevation prop',+ category: 'foundations',+ content: [+ {+ type: 'prose',+ text: 'Configurable surfaces expose a single `elevation` prop instead of asking consumers to hand-write a box-shadow. It takes the graded enum `none | low | med | high`, narrowed per component to the steps that surface needs: Card, ClickableCard, SelectableCard, Button, IconButton, ButtonGroup, Thumbnail, and Banner expose the full scale, while ChatComposer exposes only `none | low`. `none` is a flat literal (`box-shadow: none`); the other levels map to the `--shadow-*` tokens above, so a surface stays theme-agnostic.',+ },+ {+ type: 'prose',+ text: 'Prop defaults preserve current appearance: every surface defaults to `none` except ChatComposer, which defaults to `low` to keep its raised look. Set `elevation="none"` to flatten it — the flat composer draws a border with the same rest / hover / focus treatment as a text input. Thumbnail keeps its existing hover-only shadow at the `none` default.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Raising a surface with the elevation prop',+ code: `// Flat by default — raise only when the surface needs to float.+<Card elevation="low">Raised card</Card>++// A floating action button.+<IconButton icon={<Icon icon="add" />} label="New" variant="primary" elevation="med" />++// Flatten the composer (defaults to 'low').+<ChatComposer elevation="none" onSubmit={handleSubmit} />`,+ },+ {+ type: 'prose',+ text: 'Always float — no prop: intrinsic overlays (Dialog, Popover, Tooltip, Toast, HoverCard, DropdownMenu, and the components that compose them) bake their elevation in and never expose the prop. Flow content (inputs, Text, layout) is never elevated; input fields use inset rings, which are a separate concept from elevation.',+ },+ ],+ },{title: 'Usage',category: 'foundations',content: [+ {+ type: 'prose',+ text: 'When building a custom surface, read elevation from the token scale rather than a hand-rolled shadow — the same tokens the elevation prop resolves to.',+ },{type: 'code',lang: 'tsx',@@ -68,7 +143,8 @@ const styles = stylex.create({type: 'list',style: 'do',items: [- 'Match elevation to interaction context: low for tooltips, med for dropdowns, high for dialogs.',+ 'Reach for the `elevation` prop on a configurable surface before writing any custom shadow.',+ 'Choose the level by how far the surface sits from the page: `none` when flat/embedded, `low` when in-flow but distinct, `med` when over page content, `high` when over the whole UI. See "Choosing a level".','Use inset shadows for input focus/selection states; they compose better than outlines.',],},@@ -76,6 +152,8 @@ const styles = stylex.create({type: 'list',style: 'dont',items: [+ 'Hand-write a `box-shadow` in app code — set the `elevation` prop or read `shadowVars` instead.',+ 'Raise a surface that does not sit above other content — a non-overlapping surface is `none` or `low`, never `med` or `high`.','Stack multiple elevation levels on the same element.','Use elevation shadows for decorative borders. Use --color-border tokens instead.',],diff --git a/packages/cli/templates/blocks/components/Banner/BannerFloating.doc.mjs b/packages/cli/templates/blocks/components/Banner/BannerFloating.doc.mjsnew file mode 100644index 0000000000..95ba83bfdf--- /dev/null+++ b/packages/cli/templates/blocks/components/Banner/BannerFloating.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'Banner',+ name: 'Banner — Floating',+ displayName: 'Banner — Floating',+ description:+ 'A floating banner raised with `elevation="med"`. Banners are inline by default; raise one when it should read as an overlay above content.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Banner'],+};diff --git a/packages/cli/templates/blocks/components/Banner/BannerFloating.tsx b/packages/cli/templates/blocks/components/Banner/BannerFloating.tsxnew file mode 100644index 0000000000..dd9b8d00b3--- /dev/null+++ b/packages/cli/templates/blocks/components/Banner/BannerFloating.tsx@@ -0,0 +1,16 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {Banner} from '@astryxdesign/core/Banner';++export default function BannerFloating() {+ return (+ <Banner+ status="info"+ title="You have unsaved changes"+ description="A raised banner reads as an overlay floating above the page."+ elevation="med"+ />+ );+}diff --git a/packages/cli/templates/blocks/components/Button/ButtonFloating.doc.mjs b/packages/cli/templates/blocks/components/Button/ButtonFloating.doc.mjsnew file mode 100644index 0000000000..3574bc0d33--- /dev/null+++ b/packages/cli/templates/blocks/components/Button/ButtonFloating.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'Button',+ name: 'Button — Floating',+ displayName: 'Button — Floating',+ description:+ 'A floating action button raised with `elevation="med"`. Use elevation for buttons that hover above content, like a FAB.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Button', 'Icon', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Button/ButtonFloating.tsx b/packages/cli/templates/blocks/components/Button/ButtonFloating.tsxnew file mode 100644index 0000000000..95dd25d067--- /dev/null+++ b/packages/cli/templates/blocks/components/Button/ButtonFloating.tsx@@ -0,0 +1,37 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {Button} from '@astryxdesign/core/Button';+import {Icon} from '@astryxdesign/core/Icon';+import {Stack} from '@astryxdesign/core/Layout';+import {Text} from '@astryxdesign/core/Text';+import {PlusIcon} from '@heroicons/react/24/outline';++const VARIANTS = [+ {variant: 'primary' as const, label: 'Primary'},+ {variant: 'secondary' as const, label: 'Secondary'},+ {variant: 'ghost' as const, label: 'Ghost'},+ {variant: 'destructive' as const, label: 'Destructive'},+];++export default function ButtonFloating() {+ return (+ <Stack direction="vertical" gap={4}>+ <Text type="supporting" color="secondary">+ Floating action buttons — raised above content with `elevation="med"`+ </Text>+ <Stack direction="horizontal" gap={3} vAlign="center">+ {VARIANTS.map(({variant, label}) => (+ <Button+ key={variant}+ label={label}+ variant={variant}+ icon={<Icon icon={PlusIcon} />}+ elevation="med"+ />+ ))}+ </Stack>+ </Stack>+ );+}diff --git a/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupFloating.doc.mjs b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupFloating.doc.mjsnew file mode 100644index 0000000000..f781399e78--- /dev/null+++ b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupFloating.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'ButtonGroup',+ name: 'ButtonGroup — Floating',+ displayName: 'ButtonGroup — Floating',+ description:+ 'A grouped action bar raised with `elevation="med"`. The connected buttons share one surface, so the shadow lifts them as a unit.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['ButtonGroup', 'Button', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupFloating.tsx b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupFloating.tsxnew file mode 100644index 0000000000..37d1fb26a9--- /dev/null+++ b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupFloating.tsx@@ -0,0 +1,23 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {ButtonGroup} from '@astryxdesign/core/ButtonGroup';+import {Button} from '@astryxdesign/core/Button';+import {Stack} from '@astryxdesign/core/Layout';+import {Text} from '@astryxdesign/core/Text';++export default function ButtonGroupFloating() {+ return (+ <Stack direction="vertical" gap={3} hAlign="start">+ <Text type="supporting" color="secondary">+ The whole group shares one raised surface — a floating action bar+ </Text>+ <ButtonGroup label="Zoom controls" elevation="med">+ <Button label="Zoom out" />+ <Button label="Reset" />+ <Button label="Zoom in" />+ </ButtonGroup>+ </Stack>+ );+}diff --git a/packages/cli/templates/blocks/components/Card/CardElevations.doc.mjs b/packages/cli/templates/blocks/components/Card/CardElevations.doc.mjsnew file mode 100644index 0000000000..0eeaf482e4--- /dev/null+++ b/packages/cli/templates/blocks/components/Card/CardElevations.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'Card',+ name: 'Card — Elevations',+ displayName: 'Card — Elevations',+ description:+ 'The four elevation levels side by side. Cards are flat by default; raise a card with `elevation` only when it needs to float above surrounding content.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Card', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Card/CardElevations.tsx b/packages/cli/templates/blocks/components/Card/CardElevations.tsxnew file mode 100644index 0000000000..9cb8040a63--- /dev/null+++ b/packages/cli/templates/blocks/components/Card/CardElevations.tsx@@ -0,0 +1,32 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {Card} from '@astryxdesign/core/Card';+import {Stack} from '@astryxdesign/core/Layout';+import {Grid} from '@astryxdesign/core/Grid';+import {Text, Heading} from '@astryxdesign/core/Text';++const LEVELS = [+ {elevation: 'none' as const, caption: 'Flat — sits on the page (default)'},+ {elevation: 'low' as const, caption: 'Low — lifts off slightly'},+ {elevation: 'med' as const, caption: 'Med — clearly raised'},+ {elevation: 'high' as const, caption: 'High — floats well above'},+];++export default function CardElevations() {+ return (+ <Grid columns={2} gap={4} width={520}>+ {LEVELS.map(({elevation, caption}) => (+ <Card key={elevation} elevation={elevation}>+ <Stack direction="vertical" gap={1}>+ <Heading level={4}>elevation="{elevation}"</Heading>+ <Text type="supporting" color="secondary">+ {caption}+ </Text>+ </Stack>+ </Card>+ ))}+ </Grid>+ );+}diff --git a/packages/cli/templates/blocks/components/Card/ClickableCardElevated.doc.mjs b/packages/cli/templates/blocks/components/Card/ClickableCardElevated.doc.mjsnew file mode 100644index 0000000000..cf384ad200--- /dev/null+++ b/packages/cli/templates/blocks/components/Card/ClickableCardElevated.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'ClickableCard',+ name: 'ClickableCard — Elevated',+ displayName: 'Clickable Card — Elevated',+ description:+ 'A clickable card raised with `elevation="med"` so the shadow signals the whole surface is interactive.',+ isReady: true,+ aspectRatio: 1,+ componentsUsed: ['ClickableCard', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Card/ClickableCardElevated.tsx b/packages/cli/templates/blocks/components/Card/ClickableCardElevated.tsxnew file mode 100644index 0000000000..80ad925965--- /dev/null+++ b/packages/cli/templates/blocks/components/Card/ClickableCardElevated.tsx@@ -0,0 +1,21 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {ClickableCard} from '@astryxdesign/core/ClickableCard';+import {Stack} from '@astryxdesign/core/Layout';+import {Text, Heading} from '@astryxdesign/core/Text';++export default function ClickableCardElevated() {+ return (+ <ClickableCard label="Open report" href="#" elevation="med" width={320}>+ <Stack direction="vertical" gap={2}>+ <Heading level={4}>Quarterly report</Heading>+ <Text type="body" color="secondary">+ A raised shadow signals the whole card is clickable, lifting it above+ the surrounding content.+ </Text>+ </Stack>+ </ClickableCard>+ );+}diff --git a/packages/cli/templates/blocks/components/Card/SelectableCardElevated.doc.mjs b/packages/cli/templates/blocks/components/Card/SelectableCardElevated.doc.mjsnew file mode 100644index 0000000000..f67ef13b4d--- /dev/null+++ b/packages/cli/templates/blocks/components/Card/SelectableCardElevated.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'SelectableCard',+ name: 'SelectableCard — Elevated',+ displayName: 'Selectable Card — Elevated',+ description:+ 'Raised selectable cards with `elevation="low"`. The inset selection ring composes on top of the shadow, so a selected card keeps its elevation.',+ isReady: true,+ aspectRatio: 2,+ componentsUsed: ['SelectableCard', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Card/SelectableCardElevated.tsx b/packages/cli/templates/blocks/components/Card/SelectableCardElevated.tsxnew file mode 100644index 0000000000..d0b7023def--- /dev/null+++ b/packages/cli/templates/blocks/components/Card/SelectableCardElevated.tsx@@ -0,0 +1,37 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {useState} from 'react';+import {SelectableCard} from '@astryxdesign/core/SelectableCard';+import {Grid} from '@astryxdesign/core/Grid';+import {Text} from '@astryxdesign/core/Text';++const PLANS = [+ {id: 'starter', name: 'Starter'},+ {id: 'pro', name: 'Pro'},+];++export default function SelectableCardElevated() {+ const [selected, setSelected] = useState('pro');++ return (+ <Grid columns={2} gap={3} width={420}>+ {PLANS.map(plan => (+ <SelectableCard+ key={plan.id}+ label={plan.name}+ isSelected={selected === plan.id}+ onChange={() => setSelected(plan.id)}+ elevation="low">+ <Text type="body" weight="bold">+ {plan.name}+ </Text>+ <Text type="supporting" color="secondary">+ The resting shadow stays put — the selection ring layers on top.+ </Text>+ </SelectableCard>+ ))}+ </Grid>+ );+}diff --git a/packages/cli/templates/blocks/components/ChatComposer/ChatComposerFlat.doc.mjs b/packages/cli/templates/blocks/components/ChatComposer/ChatComposerFlat.doc.mjsnew file mode 100644index 0000000000..302a4f41de--- /dev/null+++ b/packages/cli/templates/blocks/components/ChatComposer/ChatComposerFlat.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'ChatComposer',+ name: 'ChatComposer — Flat',+ displayName: 'ChatComposer — Flat',+ description:+ 'The composer is raised by default (`elevation="low"`). Set `elevation="none"` to flatten it — it then draws a border with the same rest / hover / focus treatment as a text input.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['ChatComposer', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/ChatComposer/ChatComposerFlat.tsx b/packages/cli/templates/blocks/components/ChatComposer/ChatComposerFlat.tsxnew file mode 100644index 0000000000..60e332c821--- /dev/null+++ b/packages/cli/templates/blocks/components/ChatComposer/ChatComposerFlat.tsx@@ -0,0 +1,75 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {ChatComposer} from '@astryxdesign/core/Chat';+import {Button} from '@astryxdesign/core/Button';+import {DropdownMenu} from '@astryxdesign/core/DropdownMenu';+import {Icon} from '@astryxdesign/core/Icon';+import {Stack} from '@astryxdesign/core/Layout';+import {Text} from '@astryxdesign/core/Text';+import {+ Cog6ToothIcon,+ MicrophoneIcon,+ SparklesIcon,+} from '@heroicons/react/24/outline';++export default function ChatComposerFlat() {+ return (+ <Stack direction="vertical" gap={2} style={{width: '100%', maxWidth: 450}}>+ <Text type="supporting" color="secondary">+ elevation="none" — flat, with a text-input-style border and+ focus ring+ </Text>+ <ChatComposer+ elevation="none"+ onSubmit={value => {+ console.log('Sent:', value);+ }}+ footerActions={+ <>+ <DropdownMenu+ button={{+ label: 'Auto',+ variant: 'ghost',+ size: 'md',+ icon: <Icon icon={SparklesIcon} size="sm" />,+ children: 'Auto',+ }}+ menuWidth={200}+ items={[+ {label: 'Auto', onClick: () => {}},+ {label: 'Model A', onClick: () => {}},+ {label: 'Model B', onClick: () => {}},+ ]}+ />+ <DropdownMenu+ button={{+ label: 'Settings',+ variant: 'ghost',+ size: 'md',+ icon: <Icon icon={Cog6ToothIcon} size="sm" />,+ children: 'Settings',+ }}+ menuWidth={200}+ items={[+ {label: 'Preferences', onClick: () => {}},+ {label: 'Keyboard shortcuts', onClick: () => {}},+ {label: 'About', onClick: () => {}},+ ]}+ />+ </>+ }+ sendActions={+ <Button+ label="Microphone"+ variant="ghost"+ size="md"+ icon={<Icon icon={MicrophoneIcon} />}+ isIconOnly+ />+ }+ />+ </Stack>+ );+}diff --git a/packages/cli/templates/blocks/components/IconButton/IconButtonFloating.doc.mjs b/packages/cli/templates/blocks/components/IconButton/IconButtonFloating.doc.mjsnew file mode 100644index 0000000000..60d9f1323b--- /dev/null+++ b/packages/cli/templates/blocks/components/IconButton/IconButtonFloating.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'IconButton',+ name: 'IconButton — Floating',+ displayName: 'IconButton — Floating',+ description:+ 'A floating action button (FAB) — the most common floating-button shape is icon-only. Raised here with `elevation="high"`.',+ isReady: true,+ aspectRatio: 4 / 3,+ componentsUsed: ['IconButton', 'Icon', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/IconButton/IconButtonFloating.tsx b/packages/cli/templates/blocks/components/IconButton/IconButtonFloating.tsxnew file mode 100644index 0000000000..8f2cdec473--- /dev/null+++ b/packages/cli/templates/blocks/components/IconButton/IconButtonFloating.tsx@@ -0,0 +1,37 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {IconButton} from '@astryxdesign/core/IconButton';+import {Icon} from '@astryxdesign/core/Icon';+import {Stack} from '@astryxdesign/core/Layout';+import {Text} from '@astryxdesign/core/Text';+import {PlusIcon} from '@heroicons/react/24/outline';++const VARIANTS = [+ {variant: 'primary' as const, label: 'Primary'},+ {variant: 'secondary' as const, label: 'Secondary'},+ {variant: 'ghost' as const, label: 'Ghost'},+ {variant: 'destructive' as const, label: 'Destructive'},+];++export default function IconButtonFloating() {+ return (+ <Stack direction="vertical" gap={4}>+ <Text type="supporting" color="secondary">+ FABs are usually icon-only — raise one with `elevation="high"`+ </Text>+ <Stack direction="horizontal" gap={3} vAlign="center">+ {VARIANTS.map(({variant, label}) => (+ <IconButton+ key={variant}+ label={label}+ variant={variant}+ icon={<Icon icon={PlusIcon} />}+ elevation="high"+ />+ ))}+ </Stack>+ </Stack>+ );+}diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailElevated.doc.mjs b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailElevated.doc.mjsnew file mode 100644index 0000000000..af530a89f5--- /dev/null+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailElevated.doc.mjs@@ -0,0 +1,14 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'Thumbnail',+ name: 'Thumbnail — Elevated',+ displayName: 'Thumbnail — Elevated',+ description:+ 'Image tiles raised at rest with `elevation`. The default keeps the existing hover-only shadow; a set level lifts the tile off the page.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Thumbnail', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailElevated.tsx b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailElevated.tsxnew file mode 100644index 0000000000..08b9bcf5a9--- /dev/null+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailElevated.tsx@@ -0,0 +1,31 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {Thumbnail} from '@astryxdesign/core/Thumbnail';+import {Stack} from '@astryxdesign/core/Layout';+import {Text} from '@astryxdesign/core/Text';++// Demo imagery is inlined as same-origin data URIs so the example is+// self-contained. Thumbnail's remove-button overlay uses useImageMode, which+// FETCHES the image to sample pixels (APCA) for contrast — a cross-origin CDN+// URL without CORS headers cannot be sampled, so contrast detection fails+// silently in hosted previews.+const NIGHT_FOREST =+ 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAMAAACdt4HsAAAAwFBMVEX18+H08uDy8d/y8N/v7t/m5NXl49Tk4tPc3NDX1cnW1cnW1cjW1MjV1MjV1MfR0cXIyLzEw7m8vLC3t68wM0QvM0MvM0IvMkIuMkEtMEErLz8iJjkhJTggJTcgJDcfJDYfIzYeIjUcITMbHzIWHiwYGzIXGjEWGjAWGTAVGS8VGC8UGC4UGC0UFy4TFy0TFywTFi0SFiwRFSsQFSkNFR4QFCoPFCkPFCgPEykOEygOEigNEicNEScMESYIDw8ECgr+gzZIAAABqElEQVR42uWQ61aCQBRGD5GylNBMKS9FZgNdNE0cyUvB+79VM8MoF9Fgplau2j/8nO8c9hqAD0ngDwjeJYH1lrfBWoCtYDboNu/Zv7qQYNap1bpCN1gxFh1dNe5WAsCScWqoWttbChAKvHZZ0W6XQoIFpW8ooFmLCG2Rl1BgaZAU5Ac8yg0RlC9nngCRQDFuhQRzinWmkCuYk3lxQoFrlskVqlcTMcEFvYIKoFbNfmEFuIypWaGGkt66tqZuEbjAHZl6SQVF1WqNvpDAHVktXTvR9JbgDZii1+tZI7cYMJXkCASvksB4L5VxHmAsibzgRRIYbjgfCgFDSeBZkh8W1HMIniSBR0mOQPCQA3RgBk4M5DhNZwdEcbKgLXy5iDiZg5gApRYbqTql2FZgMxAKeEWSNUFYx3s2SfU28HPWItrpySSwE2cEdqrYtxgmxgHGScFmHrAGk8SxczIxZnNC1McFOGshShyb4yxB9sI3CXDGnH0MLsD7F5LvvptEgH12Zg1Pn2WuHsjvrwt8308t+nwxT38sgiAE8/RTeagH+vx/F8SeF0Ja8Ak14ia/LgmpZQAAAABJRU5ErkJggg==';+const GOLDEN_SUNSET =+ 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAMAAACdt4HsAAAAkFBMVEX/+uv/7sj6tFr3sVn1r1nzrVjxq1jvqVftp1frpVbpo1bnoVXln1XjnVThm1TfmVPdl1PblVLZk1LXkVLVj1HTjVHRi1DPiVDNh0/LhU/Jg07HgU7Ff03DfU3Be0y/eUy9d0u7dUu5c0u2cEq0bkqybEmwakmuaEisZkiqZEeoYkemYEakXkaiXEVgLjQ8HCjaJlMkAAABI0lEQVR42u3Mx3qDMBSE0Z/03nsvdhxjcnn/twsYjISR5MUkO5+V9N2ZYUPEpogtEdsidkTsitgTsS/iQMShiCMRxyJORJyKOBNxLuJCxKWIKxHXIm5E3Iq4E3Ev4kHEo4gnEc8iXkS8inhLymrJBO8J2UIiw0dc5sRDfEbVRWr1o/pbMMWox9yz6zcLIzMbBTD2VaHu7fr1gjXGA3w5baj5+H0w6x09TDpdaP7rDZhn0sd3y89Y9fcHbPnoYdroZ2w6dQNmg6OHfG4QyrsBC8gdZpVQxtqF4M1mjepFURThTLNgMYsePxaX2WqY6D8GSm2grK2slbGBciHZ9hOE2smNpTuxenhieCdeH06E7qTqvYnImWTbbUSPlKL1wHrgTwZ+AWq+3H5MpRkwAAAAAElFTkSuQmCC';++export default function ThumbnailElevated() {+ return (+ <Stack direction="vertical" gap={3}>+ <Text type="supporting" color="secondary">+ Raised tiles — `elevation` lifts an image off the page at rest+ </Text>+ <Stack direction="horizontal" gap={3} vAlign="center">+ <Thumbnail src={NIGHT_FOREST} alt="Forest at night" elevation="low" />+ <Thumbnail src={GOLDEN_SUNSET} alt="Golden sunset" elevation="high" />+ </Stack>+ </Stack>+ );+}diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjsindex 9fc9ae8371..79e6a93620 100644--- a/packages/core/src/Banner/Banner.doc.mjs+++ b/packages/core/src/Banner/Banner.doc.mjs@@ -81,6 +81,13 @@ export const docs = {'Container type: card has border-radius; section is full-width with no border-radius for page-level use.',default: "'card'",},+ {+ name: 'elevation',+ type: "'none' | 'low' | 'med' | 'high'",+ description:+ 'Resting shadow depth. Use for a floating banner that hovers above content; `none` is the default inline banner. A `card`-container banner rounds its shadow to match.',+ default: "'none'",+ },{name: 'children',type: 'ReactNode',@@ -157,6 +164,7 @@ export const docsZh = {{name: 'onDismiss', type: '() => void', description: '点击关闭按钮时调用;无论是否提供此回调,横幅都会自动隐藏。'},{name: 'endContent', type: 'ReactNode', description: '渲染在头部区域末端对齐的操作内容,通常是按钮或链接。'},{name: 'container', type: "'card' | 'section'", description: '视觉变体:card 带圆角;section 无圆角全宽,适用于页面级场景。', default: "'card'"},+ {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。用于悬浮于内容之上的浮动横幅;none 为默认内联横幅。', default: "'none'"},{name: 'children', type: 'ReactNode', description: '渲染在彩色头部下方卡片背景区域的内容。'},{name: 'defaultIsExpanded', type: 'boolean', description: '内容区域(children)是否初始展开。仅在提供 children 时相关。', default: 'false'},{@@ -230,6 +238,7 @@ export const docsDense = {onDismiss: 'dismiss callback; banner self-hides regardless',endContent: 'end-aligned action in header, typically button/link',container: 'card=border-radius; section=full-width no radius for page-level',+ elevation: 'resting shadow depth: none|low|med|high; raise for a floating banner',children: 'content in card-bg area below colored header',xstyle: 'StyleX layout customization via stylex.create()',},diff --git a/packages/core/src/Banner/Banner.test.tsx b/packages/core/src/Banner/Banner.test.tsxindex 16d1e63c36..b4bbc5eee4 100644--- a/packages/core/src/Banner/Banner.test.tsx+++ b/packages/core/src/Banner/Banner.test.tsx@@ -368,4 +368,34 @@ describe('Banner', () => {);expect(screen.getByTestId('custom-chevron')).toBeInTheDocument();});++ describe('elevation', () => {+ it('renders a distinct root class for each elevation level', () => {+ const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {+ const {container} = render(+ <Banner status="info" title="Heads up" elevation={elevation} />,+ );+ return container.firstElementChild!.className;+ };+ const classes = new Set([+ classFor('none'),+ classFor('low'),+ classFor('med'),+ classFor('high'),+ ]);+ expect(classes.size).toBe(4);+ });++ it('defaults to flat (elevation none)', () => {+ const {container: def} = render(+ <Banner status="info" title="Heads up" />,+ );+ const {container: none} = render(+ <Banner status="info" title="Heads up" elevation="none" />,+ );+ expect(def.firstElementChild!.className).toBe(+ none.firstElementChild!.className,+ );+ });+ });});diff --git a/packages/core/src/Banner/Banner.tsx b/packages/core/src/Banner/Banner.tsxindex 04c7efed0f..f125076da9 100644--- a/packages/core/src/Banner/Banner.tsx+++ b/packages/core/src/Banner/Banner.tsx@@ -46,8 +46,10 @@ import {borderVars,durationVars,easeVars,+ shadowVars,} from '../theme/tokens.stylex';import {mergeProps} from '../utils';+import type {Elevation} from '../utils/types';import {edgeCompSlot} from '../Layout/edgeCompensation.stylex';import {themeProps} from '../utils/themeProps';import {useTranslator} from '../i18n';@@ -157,6 +159,13 @@ export interface BannerProps extends BaseProps<HTMLDivElement> {* @default 'card'*/container?: BannerContainer;+ /**+ * Resting elevation — the shadow depth the banner sits at. Use for a+ * floating banner that hovers above content. `none` is the default inline+ * banner.+ * @default 'none'+ */+ elevation?: Elevation;/*** Whether the content area (children) starts expanded.* Only relevant when children are provided.@@ -215,6 +224,11 @@ const styles = stylex.create({flexDirection: 'column',fontFamily: 'inherit',},+ // When elevated, a card-container banner rounds its root so the shadow+ // follows the same silhouette as the header/content border-radius.+ rootElevatedCard: {+ borderRadius: radiusVars['--radius-container'],+ },// Header area — colored status background with icon, title, description, actions// This is the primary theme target ('banner')header: {@@ -323,6 +337,18 @@ const statusStyles = stylex.create({},});+// Resting elevation for the banner. Applied to the root so the shadow wraps+// the whole banner (header + optional content). 'none' is the default and+// leaves the layout-only root untouched. For the `card` container the root is+// rounded (rootElevatedCard) so the shadow follows the card silhouette; the+// full-width `section` container stays square.+const elevationStyles = stylex.create({+ none: {boxShadow: 'none'},+ low: {boxShadow: shadowVars['--shadow-low']},+ med: {boxShadow: shadowVars['--shadow-med']},+ high: {boxShadow: shadowVars['--shadow-high']},+});+// =============================================================================// Component// =============================================================================@@ -381,6 +407,7 @@ export function Banner({onDismiss,endContent,container = 'card',+ elevation = 'none',defaultIsExpanded = false,children,xstyle,@@ -429,7 +456,16 @@ export function Banner({<divref={ref}role={role}- {...mergeProps(stylex.props(styles.root, xstyle), className, style)}+ {...mergeProps(+ stylex.props(+ styles.root,+ elevationStyles[elevation],+ isCard && elevation !== 'none' && styles.rootElevatedCard,+ xstyle,+ ),+ className,+ style,+ )}{...rest}>{/* Header: colored status background — primary theme target ('banner') */}<divdiff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjsindex cb8ec82f9c..9aec8e6b89 100644--- a/packages/core/src/Button/Button.doc.mjs+++ b/packages/core/src/Button/Button.doc.mjs@@ -51,6 +51,13 @@ export const docs = {description: 'Size variant.',default: "'md'",},+ {+ name: 'elevation',+ type: "'none' | 'low' | 'med' | 'high'",+ description:+ 'Resting shadow depth for floating buttons (e.g. a FAB). `none` is the default flat button; `low`/`med`/`high` map to the shadow token scale. Ignored inside a ButtonGroup, where elevation is owned by the group.',+ default: "'none'",+ },{name: 'type',type: "'button' | 'submit' | 'reset'",@@ -199,6 +206,7 @@ export const docsZh = {default: "'secondary'",},{name: 'size', type: "'sm' | 'md' | 'lg'", description: '尺寸变体。', default: "'md'"},+ {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '浮动按钮(如 FAB)的静止阴影深度。`none` 为默认扁平按钮;在 ButtonGroup 内忽略。', default: "'none'"},{name: 'type', type: "'button' | 'submit' | 'reset'", description: 'HTML 按钮类型属性。', default: "'button'"},{name: 'name', type: 'string', description: '表单提交的 HTML name 属性。'},{name: 'value', type: 'string | number | readonly string[]', description: '表单提交的 HTML value 属性。'},@@ -271,6 +279,7 @@ export const docsDense = {label: 'accessible label; visible text by default, aria-label when isIconOnly',variant: 'visual style variant',size: 'size variant',+ elevation: 'resting shadow depth for floating buttons/FABs: none|low|med|high; ignored inside ButtonGroup',type: 'HTML button type; defaults to "button"',name: 'HTML name for form submission',displayName: 'HTML name for form submission',diff --git a/packages/core/src/Button/Button.test.tsx b/packages/core/src/Button/Button.test.tsxindex 390ff1584b..7f02e2c50a 100644--- a/packages/core/src/Button/Button.test.tsx+++ b/packages/core/src/Button/Button.test.tsx@@ -446,6 +446,34 @@ describe('Button', () => {expect(liveRegion).toHaveTextContent('Loading');});+ describe('elevation', () => {+ it('renders a distinct class for each elevation level', () => {+ const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {+ const {container} = render(+ <Button label="Save" elevation={elevation} />,+ );+ return container.querySelector('button')!.className;+ };+ const classes = new Set([+ classFor('none'),+ classFor('low'),+ classFor('med'),+ classFor('high'),+ ]);+ expect(classes.size).toBe(4);+ });++ it('defaults to flat (elevation none)', () => {+ const {container: def} = render(<Button label="Save" />);+ const {container: none} = render(+ <Button label="Save" elevation="none" />,+ );+ expect(def.querySelector('button')!.className).toBe(+ none.querySelector('button')!.className,+ );+ });+ });+it('exposes aria-busy on the link-rendered button while loading', () => {// Non-interruptible loading disables the button, which falls back to// <button> rendering — so an anchor only shows loading when interruptible.diff --git a/packages/core/src/Button/Button.tsx b/packages/core/src/Button/Button.tsxindex a16cd35b7c..624ee30f18 100644--- a/packages/core/src/Button/Button.tsx+++ b/packages/core/src/Button/Button.tsx@@ -20,7 +20,7 @@import {useRef, useTransition, type ReactNode} from 'react';import type {BaseProps} from '../BaseProps';-import type {SizeValue} from '../utils/types';+import type {Elevation, SizeValue} from '../utils/types';import * as stylex from '@stylexjs/stylex';import {useTooltip} from '../Tooltip/useTooltip';import {@@ -33,6 +33,7 @@ import {easeVars,fontWeightVars,typeScaleVars,+ shadowVars,} from '../theme/tokens.stylex';import {Spinner} from '../Spinner';import {VisuallyHidden} from '../VisuallyHidden';@@ -160,6 +161,18 @@ const iconSizeStyles = stylex.create({lg: {width: 20, height: 20, fontSize: 20},});+/**+ * Resting elevation for floating buttons (e.g. a FAB). `none` is the default+ * flat button; `low`/`med`/`high` map to the shadow token scale. 'none' stays+ * a literal so it never conflicts with a variant's background layering.+ */+const elevationStyles = stylex.create({+ none: {boxShadow: 'none'},+ low: {boxShadow: shadowVars['--shadow-low']},+ med: {boxShadow: shadowVars['--shadow-med']},+ high: {boxShadow: shadowVars['--shadow-high']},+});+/*** Variant styles using backgroundImage for layered colors* Pseudo-classes are nested within properties per StyleX recommendation@@ -307,6 +320,12 @@ export interface ButtonProps extends BaseProps<HTMLButtonElement> {* @default 'md'*/size?: ButtonSize;+ /**+ * Resting elevation — the shadow depth the button sits at. Use for floating+ * buttons (FABs) that hover above content. `none` is the default flat button.+ * @default 'none'+ */+ elevation?: Elevation;/*** Whether the button is disabled.* @default false@@ -578,6 +597,7 @@ export function Button({icon,isIconOnly = false,width,+ elevation = 'none',children,endContent,tooltip,@@ -691,6 +711,9 @@ export function Button({(buttonGroup.orientation === 'horizontal'? groupStyles.onSolidHorizontal: groupStyles.onSolidVertical),+ // Standalone floating buttons only — a grouped button's elevation is owned+ // by the ButtonGroup so the shared surface lifts as one unit.+ !buttonGroup && elevationStyles[elevation],width != null && dynamicStyles.width(width),xstyle,);diff --git a/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs b/packages/core/src/ButtonGroup/ButtonGroup.doc.mjsindex a520dda8f0..ada0d35e44 100644--- a/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs+++ b/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs@@ -29,6 +29,7 @@ export const docs = {{name: 'orientation', type: "'horizontal' | 'vertical'", description: 'Layout direction of the button group.', default: "'horizontal'"},{name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Default size for buttons in the group. Individual buttons can override.', default: "'md'"},{name: 'isDisabled', type: 'boolean', description: 'Whether all buttons in the group are disabled.', default: 'false'},+ {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: 'Resting shadow depth for the whole group. The connected buttons share one surface, so the shadow lifts them as a unit. Use for a group that floats above content.', default: "'none'"},{name: 'ref', type: 'React.Ref<HTMLDivElement>', description: 'Ref forwarded to the root element.'},{name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization. Must be a stylex.create() value.'},{name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},@@ -66,6 +67,7 @@ export const docsZh = {orientation: '按钮组的布局方向。',size: '组内按钮的默认尺寸。单个按钮可覆盖。',isDisabled: '组内所有按钮是否禁用。',+ elevation: '整个组的静止阴影深度。连接的按钮共享一个表面,阴影将它们作为整体抬起。',ref: '转发到根元素的引用。',xstyle: 'StyleX 样式,用于布局自定义。必须是 stylex.create() 的值。','data-testid': '自动化测试的选择器。',@@ -116,6 +118,7 @@ export const docsDense = {orientation: 'layout direction',size: 'default btn size; individual btns override',isDisabled: 'all btns disabled',+ elevation: 'resting shadow depth for whole group: none|low|med|high',xstyle: 'StyleX layout styles; must be stylex.create() value','data-testid': 'test selector',},diff --git a/packages/core/src/ButtonGroup/ButtonGroup.test.tsx b/packages/core/src/ButtonGroup/ButtonGroup.test.tsxindex 6e16b564d0..8f49f033ef 100644--- a/packages/core/src/ButtonGroup/ButtonGroup.test.tsx+++ b/packages/core/src/ButtonGroup/ButtonGroup.test.tsx@@ -572,4 +572,41 @@ describe('ButtonGroup', () => {expect(hasRoundedTrailingCorners(save)).toBe(false);});});++ describe('elevation', () => {+ it('renders a distinct class on the group for each elevation level', () => {+ const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {+ const {container} = render(+ <ButtonGroup label="Actions" elevation={elevation}>+ <Button label="One" />+ <Button label="Two" />+ </ButtonGroup>,+ );+ return container.querySelector('[role="group"]')!.className;+ };+ const classes = new Set([+ classFor('none'),+ classFor('low'),+ classFor('med'),+ classFor('high'),+ ]);+ expect(classes.size).toBe(4);+ });++ it('defaults to flat (elevation none)', () => {+ const {container: def} = render(+ <ButtonGroup label="Actions">+ <Button label="One" />+ </ButtonGroup>,+ );+ const {container: none} = render(+ <ButtonGroup label="Actions" elevation="none">+ <Button label="One" />+ </ButtonGroup>,+ );+ expect(def.querySelector('[role="group"]')!.className).toBe(+ none.querySelector('[role="group"]')!.className,+ );+ });+ });});diff --git a/packages/core/src/ButtonGroup/ButtonGroup.tsx b/packages/core/src/ButtonGroup/ButtonGroup.tsxindex 3280157268..feecacc19f 100644--- a/packages/core/src/ButtonGroup/ButtonGroup.tsx+++ b/packages/core/src/ButtonGroup/ButtonGroup.tsx@@ -24,6 +24,8 @@import {useMemo, type ReactNode} from 'react';import * as stylex from '@stylexjs/stylex';import type {ButtonSize} from '../Button';+import {radiusVars, shadowVars} from '../theme/tokens.stylex';+import type {Elevation} from '../utils/types';import {SizeProvider, useSize} from '../SizeContext/SizeContext';import {useListFocus} from '../hooks/useListFocus';import {mergeProps, mergeRefs, composeEventHandlers} from '../utils';@@ -63,6 +65,14 @@ export interface ButtonGroupProps extends BaseProps<HTMLDivElement> {*/size?: ButtonSize;+ /**+ * Resting elevation for the group. The connected buttons share one surface,+ * so the shadow sits on the group and lifts them together. Use for a floating+ * group of actions above content.+ * @default 'none'+ */+ elevation?: Elevation;+/*** Whether all buttons in the group are disabled.* @default false@@ -89,6 +99,26 @@ const styles = stylex.create({},});+// Resting elevation for the whole group — the connected buttons share one+// surface, so the shadow sits on the group wrapper and lifts them as a unit.+// The wrapper takes the element radius so the shadow follows the group's+// rounded outer corners rather than a bare rectangle. 'none' is the default.+const elevationStyles = stylex.create({+ none: {boxShadow: 'none'},+ low: {+ boxShadow: shadowVars['--shadow-low'],+ borderRadius: radiusVars['--radius-element'],+ },+ med: {+ boxShadow: shadowVars['--shadow-med'],+ borderRadius: radiusVars['--radius-element'],+ },+ high: {+ boxShadow: shadowVars['--shadow-high'],+ borderRadius: radiusVars['--radius-element'],+ },+});+// =============================================================================// Component// =============================================================================@@ -129,6 +159,7 @@ export function ButtonGroup({orientation = 'horizontal',size: sizeProp,isDisabled = false,+ elevation = 'none',xstyle,className,style,@@ -160,6 +191,7 @@ export function ButtonGroup({stylex.props(styles.group,orientation === 'vertical' && styles.vertical,+ elevationStyles[elevation],xstyle,),className,diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjsindex c4f2fc39c2..486a684d4f 100644--- a/packages/core/src/Card/Card.doc.mjs+++ b/packages/core/src/Card/Card.doc.mjs@@ -67,6 +67,13 @@ export const docs = {'Background color variant. `default` uses the standard card background. `transparent` drops the background entirely. `muted` uses the muted background for de-emphasised cards. The non-semantic variants use the corresponding `--color-background-<name>` token.',default: "'default'",},+ {+ name: 'elevation',+ type: "'none' | 'low' | 'med' | 'high'",+ description:+ 'Resting shadow depth. `none` is flat; `low`/`med`/`high` map to the shadow token scale. Raise a card only when it needs to float above surrounding content.',+ default: "'none'",+ },],playground: {defaults: {@@ -127,6 +134,7 @@ export const docsZh = {{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: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。`none` 为扁平;`low`/`med`/`high` 对应阴影令牌比例。', default: "'none'"},],theming: {container: true,@@ -170,5 +178,6 @@ export const docsDense = {children: 'content inside card',padding: 'internal padding via spacing scale',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 bb7a3d35fc..e7b3601d40 100644--- a/packages/core/src/Card/Card.test.tsx+++ b/packages/core/src/Card/Card.test.tsx@@ -17,11 +17,29 @@ describe('Card', () => {});it('renders transparent variant with variant class', () => {- const {container} = render(- <Card variant="transparent">Content</Card>,- );+ const {container} = render(<Card variant="transparent">Content</Card>);const root = container.firstElementChild!;expect(root.className).toContain('astryx-card');expect(root.className).toContain('transparent');});++ it('applies a distinct class for each elevation level', () => {+ const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {+ 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,+ );+ });});diff --git a/packages/core/src/Card/Card.tsx b/packages/core/src/Card/Card.tsxindex 6653f9dc8a..f48499bd19 100644--- a/packages/core/src/Card/Card.tsx+++ b/packages/core/src/Card/Card.tsx@@ -17,7 +17,12 @@import type {ReactNode} from 'react';import * as stylex from '@stylexjs/stylex';-import {borderVars, colorVars, radiusVars} from '../theme/tokens.stylex';+import {+ borderVars,+ colorVars,+ radiusVars,+ shadowVars,+} from '../theme/tokens.stylex';import {container} from '../Layout/container.stylex';import type {SpacingToken} from '../Layout/container.stylex';import {@@ -27,7 +32,7 @@ import {containerPaddingBlockEndVarStyles,spacingStepToToken,} from '../Layout/padding.stylex';-import type {SizeValue, SpacingStep} from '../utils/types';+import type {Elevation, SizeValue, SpacingStep} from '../utils/types';import {mergeProps} from '../utils';import type {BaseProps} from '../BaseProps';import {themeProps} from '../utils/themeProps';@@ -73,6 +78,13 @@ const styles = stylex.create({'--_card-radius': radiusVars['--radius-container'],borderRadius: 'var(--_card-radius)',overflow: 'clip',+ // Resting elevation is set via --_card-elevation (see elevationStyles).+ // The shadow list also reads --_card-ring so composing surfaces — e.g.+ // SelectableCard's inset selection ring — can layer their own shadow+ // alongside elevation instead of clobbering the single box-shadow property.+ // Unset vars fall back to a transparent no-op shadow.+ boxShadow:+ 'var(--_card-ring, 0 0 transparent), var(--_card-elevation, 0 0 transparent)',},// The border is drawn *inside* the padding — its width is subtracted from// each side — so total inset (border + padding) equals the padding token@@ -135,6 +147,18 @@ const variantStyles = stylex.create({},});+// Elevation → shadow-token map. Sets the private --_card-elevation variable+// (not box-shadow directly) so it composes with --_card-ring in the shadow+// list above — a selection ring and a resting elevation coexist without one+// overwriting the other. 'none' is a transparent no-op (not the CSS literal+// `none`, which would be invalid inside the comma-separated shadow list).+const elevationStyles = stylex.create({+ none: {'--_card-elevation': '0 0 transparent'},+ low: {'--_card-elevation': shadowVars['--shadow-low']},+ med: {'--_card-elevation': shadowVars['--shadow-med']},+ high: {'--_card-elevation': shadowVars['--shadow-high']},+});+// Dynamic styles for sizing propsconst dynamicStyles = stylex.create({sizing: (@@ -208,6 +232,13 @@ export interface CardProps extends BaseProps<HTMLDivElement> {* @default 'default'*/variant?: CardVariant;++ /**+ * Resting elevation — the shadow depth the card sits at.+ * `none` is flat; `low`/`med`/`high` map to the shadow token scale.+ * @default 'none'+ */+ elevation?: Elevation;}/**@@ -252,6 +283,7 @@ export function Card({children,padding,variant = 'default',+ elevation = 'none',xstyle,className,style,@@ -274,6 +306,7 @@ export function Card({stylex.props(styles.card,variantStyles[variant],+ elevationStyles[elevation],hasFixedHeight && styles.scrollable,dynamicStyles.sizing(width ?? null,diff --git a/packages/core/src/Chat/ChatComposer.doc.mjs b/packages/core/src/Chat/ChatComposer.doc.mjsindex 79ae216b56..974e732dd3 100644--- a/packages/core/src/Chat/ChatComposer.doc.mjs+++ b/packages/core/src/Chat/ChatComposer.doc.mjs@@ -56,6 +56,13 @@ export const docs = {description: 'Visual density.',default: "'balanced'",},+ {+ name: 'elevation',+ type: "'none' | 'low'",+ description:+ "Resting elevation of the composer body. `low` (the default) keeps today's raised look — low at rest, bumping to med on hover / focus. `none` flattens it and draws a border with the same rest / hover / focus treatment as a text input (emphasized border → accent on focus, matching inset rings).",+ default: "'low'",+ },{name: 'drawer',type: 'ReactNode',@@ -185,6 +192,7 @@ export const docsZh = {placeholder: '输入为空时显示的占位文本。',isDisabled: '禁用编写器。',density: '视觉密度。',+ elevation: "编写器主体的静止高度。low(默认)保持当前的抬起外观——静止时 low,悬停/聚焦时升至 med。none 则扁平化。",drawer: '插槽:输入上方的可折叠抽屉——附件、上下文标签等。使用 ChatComposerDrawer。',headerActions: '插槽:标题左侧操作按钮(附件、提及按钮)。使用仅图标 size="sm" 按钮。',headerContext: '插槽:标题右侧上下文信息(上下文窗口使用情况、ProgressBar、辅助文本)。',@@ -210,6 +218,7 @@ export const docsDense = {placeholder: 'placeholder when empty',isDisabled: 'disabled; use during streaming or unmet prereqs',density: 'visual density',+ elevation: "resting elevation of composer body: low (default; low→med on hover/focus) | none (flat)",drawer: 'slot: collapsible drawer above input: attachments, context chips, etc.; use ChatComposerDrawer',headerActions: 'slot: left header actions (attach, mention); icon-only sm buttons',headerContext: 'slot: right header context info (window usage, ProgressBar, text)',diff --git a/packages/core/src/Chat/ChatComposer.test.tsx b/packages/core/src/Chat/ChatComposer.test.tsxnew file mode 100644index 0000000000..4d0837b214--- /dev/null+++ b/packages/core/src/Chat/ChatComposer.test.tsx@@ -0,0 +1,35 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, it, expect} from 'vitest';+import {render} from '@testing-library/react';+import {ChatComposer} from './ChatComposer';++// The composer body — the elevated surface — is the div that wraps the input+// area (styles.body). A custom `input` slot renders inside the inputArea div,+// so the body is two ancestors up from the slot marker. Walking from a known+// marker keeps this independent of StyleX's generated class names.+function renderBodyClass(elevation?: 'none' | 'low'): string {+ const {container} = render(+ <ChatComposer+ onSubmit={() => {}}+ elevation={elevation}+ input={<div data-testid="composer-input-marker" />}+ />,+ );+ const marker = container.querySelector(+ '[data-testid="composer-input-marker"]',+ )!;+ const inputArea = marker.parentElement!;+ const body = inputArea.parentElement!;+ return body.className;+}++describe('ChatComposer elevation', () => {+ it('applies a distinct body class for each supported level', () => {+ expect(renderBodyClass('none')).not.toBe(renderBodyClass('low'));+ });++ it("defaults to 'low' (preserves the raised look)", () => {+ expect(renderBodyClass(undefined)).toBe(renderBodyClass('low'));+ });+});diff --git a/packages/core/src/Chat/ChatComposer.tsx b/packages/core/src/Chat/ChatComposer.tsxindex f58ea289c6..ead3c4d531 100644--- a/packages/core/src/Chat/ChatComposer.tsx+++ b/packages/core/src/Chat/ChatComposer.tsx@@ -40,6 +40,7 @@ import {shadowVars,durationVars,easeVars,+ borderVars,typeScaleVars,typographyVars,} from '../theme/tokens.stylex';@@ -83,6 +84,14 @@ export interface ChatComposerProps extends Omit<isDisabled?: boolean;/** Density variant */density?: ChatComposerDensity;+ /**+ * Resting elevation of the composer body. `low` (the default) keeps today's+ * raised look — low at rest, bumping to med on hover / focus. `none` flattens+ * it and draws a border with the same rest / hover / focus treatment as a+ * text input (emphasized border → accent on focus, with matching inset rings).+ * @default 'low'+ */+ elevation?: 'none' | 'low';// --- Slot props ---@@ -143,14 +152,7 @@ const styles = stylex.create({borderRadius: 'var(--_chat-composer-radius)',backgroundColor: colorVars['--color-background-popover'],cursor: 'text',- boxShadow: {- default: shadowVars['--shadow-low'],- ':hover': {'@media (hover: hover)': shadowVars['--shadow-med']},- },- transition: `box-shadow ${durationVars['--duration-fast']} ${easeVars['--ease-standard']}`,- ':focus-within': {- boxShadow: shadowVars['--shadow-med'],- },+ transition: `box-shadow ${durationVars['--duration-fast']} ${easeVars['--ease-standard']}, border-color ${durationVars['--duration-fast']} ${easeVars['--ease-standard']}`,},header: {display: 'flex',@@ -247,11 +249,56 @@ const styles = stylex.create({color: colorVars['--color-text-yellow'],},compact: {- padding: spacingVars['--spacing-2'],+ // Override the padding var (not the `padding` property) so both the base+ // body padding and the border-inset calc in elevationStyles.none pick up+ // the compact value. Scoped to the body element, so the status bar (which+ // reads the var from root) keeps its own padding.+ '--_chat-composer-padding': spacingVars['--spacing-2'],gap: spacingVars['--spacing-1'],},});+// Resting elevation for the composer body, narrowed to two steps.+// - `low` (default) preserves today's look: low at rest, bumping to med on+// hover / focus-within (a CSS-only interaction state the component owns).+// - `none` is flat; depth comes from a border + inset rings instead. The+// border is drawn *inside* the padding — its width is subtracted from every+// side (like Card) so total inset (border + padding) equals the elevated+// case and content geometry is unchanged. Border color, hover, and focus+// states mirror TextInput (shared `inputWrapperStyles.base` treatment):+// emphasized border at rest → accent on focus-within, with the same inset+// shadow rings on hover and focus.+const elevationStyles = stylex.create({+ low: {+ boxShadow: {+ default: shadowVars['--shadow-low'],+ ':hover': {'@media (hover: hover)': shadowVars['--shadow-med']},+ },+ ':focus-within': {+ boxShadow: shadowVars['--shadow-med'],+ },+ },+ none: {+ borderWidth: borderVars['--border-width'],+ borderStyle: 'solid',+ borderColor: {+ default: colorVars['--color-border-emphasized'],+ ':focus-within': colorVars['--color-accent'],+ },+ // Draw the border *inside* the padding — subtract its width from the body+ // padding (like Card's withBorder) so total inset (border + padding) equals+ // the elevated case and content geometry is unchanged.+ padding: `calc(var(--_chat-composer-padding) - ${borderVars['--border-width']})`,+ boxShadow: {+ default: 'none',+ ':hover:not(:focus-within)': {+ '@media (hover: hover)': `inset 0px 0px 0px 2px color-mix(in srgb, ${colorVars['--color-border-emphasized']} 30%, transparent)`,+ },+ ':focus-within': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,+ },+ },+});+// =============================================================================// Component// =============================================================================@@ -280,6 +327,7 @@ export function ChatComposer(props: ChatComposerProps) {placeholder: placeholderFromProps,isDisabled = false,density = 'balanced',+ elevation = 'low',drawer,headerActions,headerContext,@@ -402,6 +450,7 @@ export function ChatComposer(props: ChatComposerProps) {onClick={handleBodyClick}{...stylex.props(styles.body,+ elevationStyles[elevation],density === 'compact' && styles.compact,xstyle,)}>diff --git a/packages/core/src/ClickableCard/ClickableCard.doc.mjs b/packages/core/src/ClickableCard/ClickableCard.doc.mjsindex 0cc92aec7b..3c8ea072ed 100644--- a/packages/core/src/ClickableCard/ClickableCard.doc.mjs+++ b/packages/core/src/ClickableCard/ClickableCard.doc.mjs@@ -28,6 +28,7 @@ export const docs = {{name: 'children', type: 'ReactNode', description: 'Card content.'},{name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inner padding.', default: '4'},{name: 'variant', type: "'default' | 'transparent' | 'muted' | 'blue' | 'cyan' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'", description: 'Background color variant.', default: "'default'"},+ {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: 'Resting shadow depth. Often raised to signal the whole card is clickable.', default: "'none'"},{name: 'width', type: 'SizeValue', description: 'Card width.'},{name: 'height', type: 'SizeValue', description: 'Card height.'},{name: 'maxWidth', type: 'SizeValue', description: 'Maximum card width.'},@@ -73,6 +74,7 @@ export const docsDense = {isDisabled: 'disables card',padding: 'inner padding',variant: 'background color variant',+ elevation: 'resting shadow depth: none|low|med|high; often raised to signal clickability',width: 'card width',height: 'card height',maxWidth: 'max card width',diff --git a/packages/core/src/ClickableCard/ClickableCard.test.tsx b/packages/core/src/ClickableCard/ClickableCard.test.tsxindex 6c1f94304f..ef6d67c312 100644--- a/packages/core/src/ClickableCard/ClickableCard.test.tsx+++ b/packages/core/src/ClickableCard/ClickableCard.test.tsx@@ -106,4 +106,38 @@ describe('ClickableCard', () => {const link = screen.getByRole('link', {name: 'Disabled link'});expect(link).toHaveAttribute('aria-disabled', 'true');});++ describe('elevation', () => {+ it('forwards a distinct elevation class to the card for each level', () => {+ const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {+ const {container} = render(+ <ClickableCard label="Card" elevation={elevation}>+ Content+ </ClickableCard>,+ );+ return container.firstElementChild!.className;+ };+ const classes = new Set([+ classFor('none'),+ classFor('low'),+ classFor('med'),+ classFor('high'),+ ]);+ expect(classes.size).toBe(4);+ });++ it('defaults to flat (elevation none)', () => {+ const {container: def} = render(+ <ClickableCard label="Card">Content</ClickableCard>,+ );+ const {container: none} = render(+ <ClickableCard label="Card" elevation="none">+ Content+ </ClickableCard>,+ );+ expect(def.firstElementChild!.className).toBe(+ none.firstElementChild!.className,+ );+ });+ });});diff --git a/packages/core/src/ClickableCard/ClickableCard.tsx b/packages/core/src/ClickableCard/ClickableCard.tsxindex 9802ef9371..d4958cfa71 100644--- a/packages/core/src/ClickableCard/ClickableCard.tsx+++ b/packages/core/src/ClickableCard/ClickableCard.tsx@@ -14,6 +14,7 @@* - /apps/storybook/stories/ClickableCard.stories.tsx (storybook stories)* - /packages/cli/templates/blocks/components/Card/ClickableCardShowcase.tsx (showcase block)* - /packages/cli/templates/blocks/components/Card/ClickableCardWithNestedButton.tsx (block)+ * - /packages/cli/templates/blocks/components/Card/ClickableCardElevated.tsx (block)** Composes Card for all visual styling (radius, padding, variants,* container tokens, theming). Adds an interactive wrapper with@@ -37,7 +38,7 @@ import {durationVars,easeVars,} from '../theme/tokens.stylex';-import type {SizeValue, SpacingStep} from '../utils/types';+import type {SizeValue, SpacingStep, Elevation} from '../utils/types';import {mergeProps, mergeRefs} from '../utils';import {Card} from '../Card/Card';import type {CardVariant} from '../Card/Card';@@ -197,6 +198,13 @@ export interface ClickableCardProps extends BaseProps {*/variant?: CardVariant;+ /**+ * Resting elevation — the shadow depth the card sits at. Often raised to+ * signal that the whole card is clickable.+ * @default 'none'+ */+ elevation?: Elevation;+/** Width of the card. */width?: SizeValue;@@ -253,6 +261,7 @@ export function ClickableCard({children,padding,variant = 'default',+ elevation = 'none',width,height,maxWidth,@@ -297,6 +306,7 @@ export function ClickableCard({maxWidth={maxWidth}padding={padding}variant={variant}+ elevation={elevation}{...mergeProps(themeProps('clickable-card', {variant}), {className: classNameProp,style,diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjsindex 309665084e..a23d0c5ebf 100644--- a/packages/core/src/IconButton/IconButton.doc.mjs+++ b/packages/core/src/IconButton/IconButton.doc.mjs@@ -36,6 +36,13 @@ export const docs = {description: 'Size variant.',default: "\'md\'",},+ {+ name: 'elevation',+ type: "'none' | 'low' | 'med' | 'high'",+ description:+ 'Resting shadow depth. The most common FAB shape is an icon-only button, so raise it with `low`/`med`/`high` for a floating action button. `none` is the default flat button.',+ default: "'none'",+ },{name: 'isLoading',type: 'boolean',@@ -95,6 +102,7 @@ export const docsDense = {icon: 'icon element rendered inside button',variant: 'visual style variant',size: 'size variant',+ elevation: 'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',isLoading: 'shows loading spinner + disables interaction',isDisabled: 'disables button',tooltip: 'tooltip text shown on hover',diff --git a/packages/core/src/IconButton/IconButton.test.tsx b/packages/core/src/IconButton/IconButton.test.tsxindex 3a1f898542..56970fefb0 100644--- a/packages/core/src/IconButton/IconButton.test.tsx+++ b/packages/core/src/IconButton/IconButton.test.tsx@@ -17,10 +17,7 @@ import {IconButton} from './IconButton';describe('IconButton', () => {it('renders as an icon-only button with aria-label', () => {render(- <IconButton- label="Settings"- icon={<span data-testid="icon">⚙</span>}- />,+ <IconButton label="Settings" icon={<span data-testid="icon">⚙</span>} />,);const button = screen.getByRole('button', {name: 'Settings'});expect(button).toHaveAttribute('aria-label', 'Settings');@@ -29,10 +26,7 @@ describe('IconButton', () => {it('does not render label as visible text', () => {render(- <IconButton- label="Settings"- icon={<span data-testid="icon">⚙</span>}- />,+ <IconButton label="Settings" icon={<span data-testid="icon">⚙</span>} />,);const button = screen.getByRole('button');// The label text should not appear as visible content@@ -42,11 +36,7 @@ describe('IconButton', () => {it('forwards variant prop', () => {render(- <IconButton- label="Delete"- icon={<span>🗑</span>}- variant="destructive"- />,+ <IconButton label="Delete" icon={<span>🗑</span>} variant="destructive" />,);expect(screen.getByRole('button', {name: 'Delete'})).toBeInTheDocument();});@@ -60,11 +50,7 @@ describe('IconButton', () => {const user = userEvent.setup();const handleClick = vi.fn();render(- <IconButton- label="Close"- icon={<span>✕</span>}- onClick={handleClick}- />,+ <IconButton label="Close" icon={<span>✕</span>} onClick={handleClick} />,);await user.click(screen.getByRole('button'));@@ -105,4 +91,15 @@ describe('IconButton', () => {it('has displayName set', () => {expect(IconButton.displayName).toBe('IconButton');});++ it('forwards the elevation prop through to the underlying button', () => {+ const classFor = (elevation: 'none' | 'med') => {+ const {container} = render(+ <IconButton label="Add" icon={<span>+</span>} elevation={elevation} />,+ );+ return container.querySelector('button')!.className;+ };+ // A raised FAB must render differently from the default flat icon button.+ expect(classFor('med')).not.toBe(classFor('none'));+ });});diff --git a/packages/core/src/SelectableCard/SelectableCard.doc.mjs b/packages/core/src/SelectableCard/SelectableCard.doc.mjsindex 5978e6ca55..43c613f12d 100644--- a/packages/core/src/SelectableCard/SelectableCard.doc.mjs+++ b/packages/core/src/SelectableCard/SelectableCard.doc.mjs@@ -27,6 +27,7 @@ export const docs = {{name: 'children', type: 'ReactNode', description: 'Card content.'},{name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inner padding.', default: '4'},{name: 'variant', type: "'default' | 'transparent' | 'muted' | 'blue' | 'cyan' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'", description: 'Background color variant.', default: "'default'"},+ {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: 'Resting shadow depth. The selection ring composes on top, so a selected card keeps its shadow.', default: "'none'"},{name: 'width', type: 'SizeValue', description: 'Card width.'},{name: 'height', type: 'SizeValue', description: 'Card height.'},{name: 'maxWidth', type: 'SizeValue', description: 'Maximum card width.'},@@ -71,6 +72,7 @@ export const docsDense = {isDisabled: 'disables card',padding: 'inner padding',variant: 'background color variant',+ elevation: 'resting shadow depth: none|low|med|high; selection ring composes on top',width: 'card width',height: 'card height',maxWidth: 'max card width',diff --git a/packages/core/src/SelectableCard/SelectableCard.test.tsx b/packages/core/src/SelectableCard/SelectableCard.test.tsxindex 8f0410a005..1e33517e0f 100644--- a/packages/core/src/SelectableCard/SelectableCard.test.tsx+++ b/packages/core/src/SelectableCard/SelectableCard.test.tsx@@ -85,8 +85,7 @@ describe('SelectableCard', () => {label="Disabled"isSelected={false}onChange={handleChange}- isDisabled- >+ isDisabled>Content</SelectableCard>,);@@ -101,12 +100,55 @@ describe('SelectableCard', () => {label="Disabled"isSelected={false}onChange={handleChange}- isDisabled- >+ isDisabled><span>Content</span></SelectableCard>,);fireEvent.click(screen.getByText('Content'));expect(handleChange).not.toHaveBeenCalled();});++ describe('elevation', () => {+ const noop = () => {};++ it('forwards a distinct elevation class to the card for each level', () => {+ const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {+ const {container} = render(+ <SelectableCard+ label="Card"+ isSelected={false}+ onChange={noop}+ elevation={elevation}>+ Content+ </SelectableCard>,+ );+ return container.firstElementChild!.className;+ };+ const classes = new Set([+ classFor('none'),+ classFor('low'),+ classFor('med'),+ classFor('high'),+ ]);+ expect(classes.size).toBe(4);+ });++ it('still varies elevation while selected (ring composes with elevation)', () => {+ const selectedClassFor = (elevation: 'none' | 'med') => {+ const {container} = render(+ <SelectableCard+ label="Card"+ isSelected+ onChange={noop}+ elevation={elevation}>+ Content+ </SelectableCard>,+ );+ return container.firstElementChild!.className;+ };+ // A selected card at 'med' must differ from a selected card at 'none' —+ // proving the selection ring does not clobber the elevation shadow.+ expect(selectedClassFor('med')).not.toBe(selectedClassFor('none'));+ });+ });});diff --git a/packages/core/src/SelectableCard/SelectableCard.tsx b/packages/core/src/SelectableCard/SelectableCard.tsxindex da903aa970..bfed3465b4 100644--- a/packages/core/src/SelectableCard/SelectableCard.tsx+++ b/packages/core/src/SelectableCard/SelectableCard.tsx@@ -14,6 +14,7 @@* - /apps/storybook/stories/SelectableCard.stories.tsx (storybook stories)* - /packages/cli/templates/blocks/components/Card/SelectableCardShowcase.tsx (showcase block)* - /packages/cli/templates/blocks/components/Card/SelectableCardMulti.tsx (block)+ * - /packages/cli/templates/blocks/components/Card/SelectableCardElevated.tsx (block)** Composes Card for all visual styling. Adds selection state with* an inset box-shadow (zero layout jitter) and useClickableContainer@@ -36,7 +37,7 @@ import {import * as stylex from '@stylexjs/stylex';import type {StyleXStyles} from '@stylexjs/stylex';import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';-import type {SizeValue, SpacingStep} from '../utils/types';+import type {Elevation, SizeValue, SpacingStep} from '../utils/types';import {mergeProps, mergeRefs} from '../utils';import {Card} from '../Card/Card';import type {CardVariant} from '../Card/Card';@@ -103,51 +104,54 @@ const styles = stylex.create({whiteSpace: 'nowrap',borderWidth: 0,},- // Selection indicator — inset box-shadow for the thick inner ring (zero layout- // jitter) plus borderColor change on the card's own border for a cohesive look.+ // Selection indicator — an inset ring drawn via the card's --_card-ring+ // shadow slot (zero layout jitter) plus a borderColor change on the card's+ // own border for a cohesive look. Routing the ring through --_card-ring+ // (rather than box-shadow directly) lets it compose with the card's+ // elevation instead of clobbering it.selected: {borderColor: colorVars['--color-accent'],- boxShadow: `inset 0 0 0 2px ${colorVars['--color-accent']}`,+ '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-accent']}`,},selectedBlue: {borderColor: colorVars['--color-border-blue'],- boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-blue']}`,+ '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-blue']}`,},selectedCyan: {borderColor: colorVars['--color-border-cyan'],- boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-cyan']}`,+ '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-cyan']}`,},selectedGray: {borderColor: colorVars['--color-border-gray'],- boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-gray']}`,+ '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-gray']}`,},selectedGreen: {borderColor: colorVars['--color-border-green'],- boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-green']}`,+ '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-green']}`,},selectedOrange: {borderColor: colorVars['--color-border-orange'],- boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-orange']}`,+ '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-orange']}`,},selectedPink: {borderColor: colorVars['--color-border-pink'],- boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-pink']}`,+ '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-pink']}`,},selectedPurple: {borderColor: colorVars['--color-border-purple'],- boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-purple']}`,+ '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-purple']}`,},selectedRed: {borderColor: colorVars['--color-border-red'],- boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-red']}`,+ '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-red']}`,},selectedTeal: {borderColor: colorVars['--color-border-teal'],- boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-teal']}`,+ '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-teal']}`,},selectedYellow: {borderColor: colorVars['--color-border-yellow'],- boxShadow: `inset 0 0 0 2px ${colorVars['--color-border-yellow']}`,+ '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-yellow']}`,},});@@ -228,6 +232,13 @@ export interface SelectableCardProps extends Omit<BaseProps, 'onChange'> {*/variant?: CardVariant;+ /**+ * Resting elevation — the shadow depth the card sits at.+ * The selection ring composes on top, so a selected card keeps its shadow.+ * @default 'none'+ */+ elevation?: Elevation;+/** Width of the card. */width?: SizeValue;@@ -278,6 +289,7 @@ export function SelectableCard({children,padding,variant = 'default',+ elevation = 'none',width,height,maxWidth,@@ -328,6 +340,7 @@ export function SelectableCard({maxWidth={maxWidth}padding={padding}variant={variant}+ elevation={elevation}{...mergeProps(themeProps('selectable-card', {variant,diff --git a/packages/core/src/Thumbnail/Thumbnail.doc.mjs b/packages/core/src/Thumbnail/Thumbnail.doc.mjsindex 83166ff19d..18b051eb19 100644--- a/packages/core/src/Thumbnail/Thumbnail.doc.mjs+++ b/packages/core/src/Thumbnail/Thumbnail.doc.mjs@@ -45,6 +45,13 @@ export const docs = {description: 'Whether the thumbnail is disabled.',default: 'false',},+ {+ name: 'elevation',+ type: "'none' | 'low' | 'med' | 'high'",+ description:+ 'Resting shadow depth. `none` (the default) keeps the existing hover-only shadow; set a level to raise the tile at rest.',+ default: "'none'",+ },{name: 'xstyle',type: 'StyleXStyles',@@ -101,6 +108,7 @@ export const docsZh = {onClick: '\u70B9\u51FB\u5904\u7406\u5668\u3002\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u9634\u5F71\u3002',isLoading: '\u663E\u793A\u9AA8\u67B6\u5C4F\uFF08\u65E0 src\uFF09\u6216\u4E0A\u4F20\u8986\u76D6\u5C42\uFF08\u6709 src\uFF09\u3002',isDisabled: '\u662F\u5426\u7981\u7528\u7F29\u7565\u56FE\u3002',+ elevation: '\u9759\u6B62\u9634\u5F71\u6DF1\u5EA6\uFF1Anone\uFF08\u9ED8\u8BA4\uFF0C\u4FDD\u7559\u4EC5\u60AC\u505C\u9634\u5F71\uFF09| low | med | high\u3002',xstyle: '\u7528\u4E8E\u5E03\u5C40\u81EA\u5B9A\u4E49\u7684 StyleX \u6837\u5F0F\u3002\u5FC5\u987B\u662F stylex.create() \u7684\u503C\uFF0C\u800C\u975E\u5185\u8054\u6837\u5F0F\u5BF9\u8C61\u3002',className: '\u6839\u5143\u7D20\u7684 CSS \u7C7B\u540D\u3002\u5EFA\u8BAE\u4F7F\u7528 xstyle\u3002',style: '\u6839\u5143\u7D20\u7684\u5185\u8054\u6837\u5F0F\u3002\u5EFA\u8BAE\u4F7F\u7528 xstyle\u3002',@@ -141,6 +149,7 @@ export const docsDense = {onClick: '(e) => void. Adds button semantics + hover shadow.',isLoading: 'Skeleton (no src) or upload overlay (with src). Default: false.',isDisabled: 'Disabled state. Default: false.',+ elevation: 'Resting shadow depth: none (keeps hover-only shadow) | low | med | high.',xstyle: 'stylex.create() for layout.',className: 'CSS class. Prefer xstyle.',style: 'Inline styles. Prefer xstyle.',diff --git a/packages/core/src/Thumbnail/Thumbnail.test.tsx b/packages/core/src/Thumbnail/Thumbnail.test.tsxindex bf1ca6ba6b..83b6da0432 100644--- a/packages/core/src/Thumbnail/Thumbnail.test.tsx+++ b/packages/core/src/Thumbnail/Thumbnail.test.tsx@@ -21,16 +21,19 @@ describe('Thumbnail', () => {});it('shows skeleton when isLoading with no src', () => {- const {container} = render(- <Thumbnail isLoading data-testid="thumb" />,- );+ const {container} = render(<Thumbnail isLoading data-testid="thumb" />);expect(container.querySelector('.astryx-skeleton')).toBeInTheDocument();expect(screen.queryByRole('img')).toBeNull();});it('shows image with upload overlay when isLoading with src', () => {render(- <Thumbnail src="/local.jpg" alt="Uploading" isLoading data-testid="thumb" />,+ <Thumbnail+ src="/local.jpg"+ alt="Uploading"+ isLoading+ data-testid="thumb"+ />,);const img = screen.getByRole('img');expect(img).toHaveAttribute('src', '/local.jpg');@@ -75,7 +78,6 @@ describe('Thumbnail', () => {).toBeInTheDocument();});-it('label is shown via tooltip, not as inline text', () => {render(<Thumbnail label="photo.png" data-testid="thumb" />);// Label should exist in DOM (tooltip) but not as a direct child text node@@ -117,9 +119,7 @@ describe('Thumbnail', () => {it('is not interactive when isLoading', () => {const onClick = vi.fn();- render(- <Thumbnail src="/img.jpg" alt="Test" onClick={onClick} isLoading />,- );+ render(<Thumbnail src="/img.jpg" alt="Test" onClick={onClick} isLoading />);expect(screen.queryByRole('button')).toBeNull();});@@ -128,4 +128,34 @@ describe('Thumbnail', () => {render(<Thumbnail ref={ref} data-testid="thumb" />);expect(ref).toHaveBeenCalled();});++ describe('elevation', () => {+ // The elevation class lives on the image container (the shadow surface),+ // which is the root's first element child.+ const imageContainerClass = (+ elevation: 'none' | 'low' | 'med' | 'high',+ ) => {+ const {container} = render(+ <Thumbnail src="/x.png" alt="x" elevation={elevation} />,+ );+ return container.firstElementChild!.firstElementChild!.className;+ };++ it('renders a distinct class for each elevation level', () => {+ const classes = new Set([+ imageContainerClass('none'),+ imageContainerClass('low'),+ imageContainerClass('med'),+ imageContainerClass('high'),+ ]);+ expect(classes.size).toBe(4);+ });++ it('defaults to flat (elevation none)', () => {+ const {container: def} = render(<Thumbnail src="/x.png" alt="x" />);+ expect(def.firstElementChild!.firstElementChild!.className).toBe(+ imageContainerClass('none'),+ );+ });+ });});diff --git a/packages/core/src/Thumbnail/Thumbnail.tsx b/packages/core/src/Thumbnail/Thumbnail.tsxindex 1ce0fa3f1a..022e42069a 100644--- a/packages/core/src/Thumbnail/Thumbnail.tsx+++ b/packages/core/src/Thumbnail/Thumbnail.tsx@@ -38,6 +38,7 @@ import {Tooltip} from '../Tooltip/Tooltip';import {MediaTheme} from '../theme/MediaTheme';import {useImageMode} from '../hooks/useImageMode';import type {BaseProps} from '../BaseProps';+import type {Elevation} from '../utils/types';import {mergeProps} from '../utils';import {themeProps} from '../utils/themeProps';import {useTranslator} from '../i18n';@@ -90,6 +91,12 @@ export interface ThumbnailProps extends BaseProps<HTMLDivElement> {* @default false*/isDisabled?: boolean;+ /**+ * Resting elevation — the shadow depth the tile sits at. `none` (the default)+ * keeps the existing hover-only shadow; a set level raises the tile at rest.+ * @default 'none'+ */+ elevation?: Elevation;/*** Test ID for testing frameworks.*/@@ -116,6 +123,10 @@ const styles = stylex.create({borderRadius: radiusVars['--radius-element'],overflow: 'hidden',backgroundColor: colorVars['--color-neutral'],+ // Resting elevation is set via --_thumbnail-elevation (see elevationStyles).+ // Routing it through a var lets the interactive hover bump (below) override+ // just the resting value without clobbering the elevation prop.+ boxShadow: 'var(--_thumbnail-elevation, none)',},image: {width: '100%',@@ -144,7 +155,10 @@ const styles = stylex.create({transitionDuration: durationVars['--duration-fast'],transitionTimingFunction: easeVars['--ease-standard'],boxShadow: {- default: 'none',+ // Rest at the elevation prop's level (default none); bump to med on hover+ // as before. Reading the var here keeps a set elevation visible at rest+ // instead of being reset to flat.+ default: 'var(--_thumbnail-elevation, none)',':hover': {'@media (hover: hover)': shadowVars['--shadow-med'],},@@ -201,6 +215,17 @@ const styles = stylex.create({},});+// Resting elevation → shadow token. Sets --_thumbnail-elevation (read by the+// image container and the interactive hover style) rather than box-shadow+// directly, so a set resting elevation survives the interactive hover bump.+// 'none' is the default — the existing hover-only shadow is unchanged.+const elevationStyles = stylex.create({+ none: {'--_thumbnail-elevation': 'none'},+ low: {'--_thumbnail-elevation': shadowVars['--shadow-low']},+ med: {'--_thumbnail-elevation': shadowVars['--shadow-med']},+ high: {'--_thumbnail-elevation': shadowVars['--shadow-high']},+});+// =============================================================================// Placeholder icon — a simple image silhouette// =============================================================================@@ -246,6 +271,7 @@ export function Thumbnail({onClick,isLoading = false,isDisabled = false,+ elevation = 'none',xstyle,className,style,@@ -311,6 +337,7 @@ export function Thumbnail({<div{...stylex.props(styles.imageContainer,+ elevationStyles[elevation],isInteractive && styles.interactive,)}>{isInteractive ? (diff --git a/packages/core/src/utils/types.ts b/packages/core/src/utils/types.tsindex 6b8f3e3805..18e64c1448 100644--- a/packages/core/src/utils/types.ts+++ b/packages/core/src/utils/types.ts@@ -12,6 +12,20 @@*/export type SizeValue = number | string;+/**+ * Resting elevation level for configurable surfaces.+ *+ * Maps to the shadow token scale:+ * - `none` = flat (`box-shadow: none`)+ * - `low` = `--shadow-low`+ * - `med` = `--shadow-med`+ * - `high` = `--shadow-high`+ *+ * Components narrow this union to the steps they actually need — e.g. Card+ * exposes all four, while ChatComposer exposes only `'none' | 'low'`.+ */+export type Elevation = 'none' | 'low' | 'med' | 'high';+/*** Numeric spacing step from the Astryx spacing scale.*