@astryxdesign/cli 0.1.8-canary.35b07f5 → 0.1.8-canary.3bb5896

package/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.',
           ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.8-canary.35b07f5",
+  "version": "0.1.8-canary.3bb5896",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -79,10 +79,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.8-canary.35b07f5",
-    "@astryxdesign/core": "0.1.8-canary.35b07f5",
-    "@astryxdesign/lab": "0.1.8-canary.35b07f5",
-    "@astryxdesign/theme-neutral": "0.1.8-canary.35b07f5",
+    "@astryxdesign/charts": "0.1.8-canary.3bb5896",
+    "@astryxdesign/core": "0.1.8-canary.3bb5896",
+    "@astryxdesign/lab": "0.1.8-canary.3bb5896",
+    "@astryxdesign/theme-neutral": "0.1.8-canary.3bb5896",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -100,10 +100,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.8-canary.35b07f5",
-    "@astryxdesign/core": "0.1.8-canary.35b07f5",
-    "@astryxdesign/lab": "0.1.8-canary.35b07f5",
-    "@astryxdesign/theme-neutral": "0.1.8-canary.35b07f5",
+    "@astryxdesign/charts": "0.1.8-canary.3bb5896",
+    "@astryxdesign/core": "0.1.8-canary.3bb5896",
+    "@astryxdesign/lab": "0.1.8-canary.3bb5896",
+    "@astryxdesign/theme-neutral": "0.1.8-canary.3bb5896",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/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'],
+};

package/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"
+    />
+  );
+}

package/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'],
+};

package/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>
+  );
+}

package/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'],
+};

package/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>
+  );
+}

package/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'],
+};

package/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=&quot;{elevation}&quot;</Heading>
+            <Text type="supporting" color="secondary">
+              {caption}
+            </Text>
+          </Stack>
+        </Card>
+      ))}
+    </Grid>
+  );
+}

package/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'],
+};

package/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>
+  );
+}

package/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'],
+};

package/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>
+  );
+}

package/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'],
+};

package/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=&quot;none&quot; — 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>
+  );
+}

package/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'],
+};

package/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>
+  );
+}

package/templates/blocks/components/OverflowList/OverflowListCappedToolbar.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: 'OverflowList',
+  name: 'OverflowList — Capped Toolbar',
+  displayName: 'OverflowList — Capped Toolbar',
+  description:
+    'maxVisibleItems caps the row at three actions even when more would fit; the rest move to a dropdown',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['OverflowList', 'Button', 'DropdownMenu', 'Card', 'Center'],
+};

package/templates/blocks/components/OverflowList/OverflowListCappedToolbar.tsx

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {OverflowList} from '@astryxdesign/core/OverflowList';
+import {Button} from '@astryxdesign/core/Button';
+import {DropdownMenu} from '@astryxdesign/core/DropdownMenu';
+import {Card} from '@astryxdesign/core/Card';
+import {Center} from '@astryxdesign/core/Center';
+
+const actions = ['Save', 'Edit', 'Duplicate', 'Share', 'Archive', 'Delete'];
+
+export default function OverflowListCappedToolbar() {
+  return (
+    <Center width={420}>
+      <Card padding={2}>
+        <OverflowList
+          gap={2}
+          maxVisibleItems={3}
+          overflowRenderer={overflowItems => (
+            <DropdownMenu
+              button={{
+                label: `+${overflowItems.length}`,
+                variant: 'ghost',
+                size: 'sm',
+              }}
+              items={overflowItems.map(({index}) => ({
+                label: actions[index],
+              }))}
+            />
+          )}>
+          {actions.map(action => (
+            <Button key={action} label={action} size="sm" />
+          ))}
+        </OverflowList>
+      </Card>
+    </Center>
+  );
+}

package/templates/blocks/components/OverflowList/OverflowListMultiRowTags.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: 'OverflowList',
+  name: 'OverflowList — Multi-row Tags',
+  displayName: 'OverflowList — Multi-row Tags',
+  description:
+    'Tags wrap onto up to two rows with maxRows, then collapse the rest into a count badge',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['OverflowList', 'Badge', 'Card'],
+};

package/templates/blocks/components/OverflowList/OverflowListMultiRowTags.tsx

@@ -0,0 +1,44 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {OverflowList} from '@astryxdesign/core/OverflowList';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Card} from '@astryxdesign/core/Card';
+
+const tags = [
+  'React',
+  'TypeScript',
+  'StyleX',
+  'Storybook',
+  'Vitest',
+  'Playwright',
+  'ESLint',
+  'Prettier',
+  'Vite',
+  'pnpm',
+];
+
+export default function OverflowListMultiRowTags() {
+  return (
+    <Card
+      padding={2}
+      style={{
+        resize: 'horizontal',
+        overflow: 'hidden',
+        minWidth: 120,
+        width: 260,
+      }}>
+      <OverflowList
+        gap={1}
+        maxRows={2}
+        overflowRenderer={overflowItems => (
+          <Badge variant="neutral" label={`+${overflowItems.length}`} />
+        )}>
+        {tags.map(tag => (
+          <Badge key={tag} variant="info" label={tag} />
+        ))}
+      </OverflowList>
+    </Card>
+  );
+}

package/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'],
+};

package/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>
+  );
+}