@instruments/materia-ui 0.4.4 → 0.4.6

package/agent-docs.md

@@ -80,6 +80,7 @@ Constrains its content to a fixed width-to-height ratio, sizing itself to the av
 
 - Give it exactly one child and let it fill - set the media to `size-full object-cover`; `AspectRatio` sizes to the available width and derives height from `ratio`.
 - Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+- Show a material, swatch or sample at the default 1:1 - never landscape. A sample is cut square, and a wide crop reads as room photography; set a wide `ratio` only for a scene, an interior or video.
 
 ## AttributeCard
 
@@ -1033,6 +1034,7 @@ Extracted from the product-card and editorial-card media frames; available to an
 - Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
 - Set `edge` to frame photography with an inset hairline that stays above the media; do not fake it with a border or an inset shadow on the frame, which the media hides.
 - Reach for `raised` only when the frame sits on the same fill as its surface; in a dense row the edge already separates it.
+- Frame a material, swatch or sample square: give the frame `aspect-square` (or wrap it in `AspectRatio`, which defaults to 1:1). Never crop a material landscape.
 
 ## MediaFrameEmbed
 
@@ -1244,6 +1246,7 @@ This is a presentational component that accepts handlers via props for app-speci
 
 - In Next.js apps pass `renderImage` wrapping `next/image` and `linkAs={Link}` - the defaults are a plain `<img>` and `<a>`.
 - Cart UI renders only when a `renderAddToCart` slot is provided; keep `dragAdapter` referentially stable (module-level constant).
+- Use ProductCard for a material in a grid or list; its image is square, which is how a material is always shown. Don't rebuild the card with a landscape image.
 
 ## ProductCardProvider
 
@@ -1833,6 +1836,7 @@ Chips paint the darkening overlay on every fill and draw the double-ring selecti
 - Feed fills through `color`/`background`/`colors`, never a hex in `className`/`style` - the props drive the contrast-aware text colour, selection ring, and darkening overlay.
 - Reach for `Swatch` for a selectable colour/gradient/material chip or tile; a tiny non-interactive status marker is `Dot`, and a display-only status/category label is `Badge`.
 - For a gradient or image chip fill pass `light` - auto contrast detection (`isLightColor`) only reads solid colours, so overlaid icons/labels lose legibility without it.
+- A material swatch is always square, as Swatch draws it; never stretch a tile into a landscape crop, and in a grid let the column set the size.
 
 ## SwatchFan
 

package/dist/components/aspect-ratio/aspect-ratio-root.d.ts

@@ -14,7 +14,9 @@ interface AspectRatioProps extends useRender.ComponentProps<"div"> {
     as?: LayoutElement;
     /**
      * Desired width-to-height ratio, expressed as a single number (width / height).
-     * @default 16 / 9
+     * Square unless asked: a material is shown at 1:1, and only scenes and
+     * video take a wide ratio.
+     * @default 1
      */
     ratio?: number;
 }
@@ -25,13 +27,15 @@ interface AspectRatioProps extends useRender.ComponentProps<"div"> {
  *
  * @example
  * ```tsx
- * <AspectRatio ratio={16 / 9}>
- *   <img alt="" className="size-full object-cover" src="/hero.jpg" />
+ * <AspectRatio>
+ *   <img alt="" className="size-full object-cover" src="/oak-plank.jpg" />
  * </AspectRatio>
  * ```
  *
  * @bestPractice Give it exactly one child and let it fill - set the media to `size-full object-cover`; `AspectRatio` sizes to the available width and derives height from `ratio`.
  * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ * @bestPractice Show a material, swatch or sample at the default 1:1 - never landscape. A sample is cut square, and a wide crop reads as room photography; set a wide `ratio` only for a scene, an interior or video.
+ * @keywords material image, swatch image, sample image, thumbnail, square, image ratio
  * @category layout
  */
 declare const AspectRatio: ({ as, className, ratio, ref, render, style, ...props }: AspectRatioProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/components/aspect-ratio/aspect-ratio-root.js

@@ -2,7 +2,7 @@
 import { useRender } from "@base-ui/react/use-render";
 import { cn } from "../../utils/cn.js";
 import { reportDevIssue } from "../../utils/dev-issue.js";
-const DEFAULT_RATIO = 16 / 9;
+const DEFAULT_RATIO = 1;
 /**
  * Constrains its content to a fixed width-to-height ratio, sizing itself to the
  * available width with CSS `aspect-ratio`; drop a single child (image, video,
@@ -10,13 +10,15 @@ const DEFAULT_RATIO = 16 / 9;
  *
  * @example
  * ```tsx
- * <AspectRatio ratio={16 / 9}>
- *   <img alt="" className="size-full object-cover" src="/hero.jpg" />
+ * <AspectRatio>
+ *   <img alt="" className="size-full object-cover" src="/oak-plank.jpg" />
  * </AspectRatio>
  * ```
  *
  * @bestPractice Give it exactly one child and let it fill - set the media to `size-full object-cover`; `AspectRatio` sizes to the available width and derives height from `ratio`.
  * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ * @bestPractice Show a material, swatch or sample at the default 1:1 - never landscape. A sample is cut square, and a wide crop reads as room photography; set a wide `ratio` only for a scene, an interior or video.
+ * @keywords material image, swatch image, sample image, thumbnail, square, image ratio
  * @category layout
  */
 const AspectRatio = ({ as, className, ratio = DEFAULT_RATIO, ref, render, style, ...props }) => {

package/dist/components/media-frame/media-frame-root.d.ts

@@ -51,6 +51,8 @@ export interface MediaFrameProps extends useRender.ComponentProps<"div"> {
  * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
  * @bestPractice Set `edge` to frame photography with an inset hairline that stays above the media; do not fake it with a border or an inset shadow on the frame, which the media hides.
  * @bestPractice Reach for `raised` only when the frame sits on the same fill as its surface; in a dense row the edge already separates it.
+ * @bestPractice Frame a material, swatch or sample square: give the frame `aspect-square` (or wrap it in `AspectRatio`, which defaults to 1:1). Never crop a material landscape.
+ * @keywords material image, product image, photo frame, thumbnail
  * @category layout
  */
 export declare const MediaFrame: ({ as, className, children, edge, raised, ref, render, ...props }: MediaFrameProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/components/media-frame/media-frame-root.js

@@ -25,6 +25,8 @@ import { reportDevIssue } from "../../utils/dev-issue.js";
  * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
  * @bestPractice Set `edge` to frame photography with an inset hairline that stays above the media; do not fake it with a border or an inset shadow on the frame, which the media hides.
  * @bestPractice Reach for `raised` only when the frame sits on the same fill as its surface; in a dense row the edge already separates it.
+ * @bestPractice Frame a material, swatch or sample square: give the frame `aspect-square` (or wrap it in `AspectRatio`, which defaults to 1:1). Never crop a material landscape.
+ * @keywords material image, product image, photo frame, thumbnail
  * @category layout
  */
 export const MediaFrame = ({ as, className, children, edge = false, raised = false, ref, render, ...props }) => {

package/dist/components/swatch/swatch-root.d.ts

@@ -38,6 +38,8 @@ type SwatchProps = ChipSwatchProps | TileSwatchProps;
  * @bestPractice Feed fills through `color`/`background`/`colors`, never a hex in `className`/`style` - the props drive the contrast-aware text colour, selection ring, and darkening overlay.
  * @bestPractice Reach for `Swatch` for a selectable colour/gradient/material chip or tile; a tiny non-interactive status marker is `Dot`, and a display-only status/category label is `Badge`.
  * @bestPractice For a gradient or image chip fill pass `light` - auto contrast detection (`isLightColor`) only reads solid colours, so overlaid icons/labels lose legibility without it.
+ * @bestPractice A material swatch is always square, as Swatch draws it; never stretch a tile into a landscape crop, and in a grid let the column set the size.
+ * @keywords material swatch, material sample, finish, colourway, colour chip
  * @category color
  */
 declare const Swatch: (props: SwatchProps) => import("react").JSX.Element;

package/dist/components/swatch/swatch-root.js

@@ -29,6 +29,8 @@ import { SwatchTile } from "./swatch-tile.js";
  * @bestPractice Feed fills through `color`/`background`/`colors`, never a hex in `className`/`style` - the props drive the contrast-aware text colour, selection ring, and darkening overlay.
  * @bestPractice Reach for `Swatch` for a selectable colour/gradient/material chip or tile; a tiny non-interactive status marker is `Dot`, and a display-only status/category label is `Badge`.
  * @bestPractice For a gradient or image chip fill pass `light` - auto contrast detection (`isLightColor`) only reads solid colours, so overlaid icons/labels lose legibility without it.
+ * @bestPractice A material swatch is always square, as Swatch draws it; never stretch a tile into a landscape crop, and in a grid let the column set the size.
+ * @keywords material swatch, material sample, finish, colourway, colour chip
  * @category color
  */
 const Swatch = (props) => {

package/dist/compositions/product-card/product-card-image.js

@@ -6,6 +6,7 @@ import { cn } from "@instruments/materia-ui/utils/cn";
 import { memo, useMemo } from "react";
 import { ProductCardAvailabilityStatus } from "./product-card-availability.js";
 import { useProductCard } from "./product-card-context.js";
+import { PRODUCT_CARD_IMAGE_RADIUS, PRODUCT_CARD_SWATCH_IMAGE_RADIUS, } from "./product-card-radius.js";
 /**
  * Handle used when no `dragAdapter` is provided: a static, non-draggable
  * image. Module-level so its identity is stable across renders.
@@ -24,7 +25,7 @@ const NoPhotographyState = ({ className, inspiration, productName, }) => {
     if (inspiration) {
         return (_jsx("output", { "aria-label": `Photography unavailable for ${productName}`, className: cn("bg-muted/45 absolute inset-0 overflow-hidden rounded-3xl", className), "data-component": "product-card-image-unavailable" }));
     }
-    return (_jsx("output", { "aria-label": `Photography unavailable for ${productName}`, className: cn("block w-full @[180px]/product-card:px-4 @[180px]/product-card:pt-4", className), "data-component": "product-card-image-unavailable", children: _jsx("span", { className: "bg-muted/45 block aspect-square w-full overflow-hidden rounded-3xl @[180px]/product-card:rounded-2xl" }) }));
+    return (_jsx("output", { "aria-label": `Photography unavailable for ${productName}`, className: cn("block w-full @[180px]/product-card:px-4 @[180px]/product-card:pt-4", className), "data-component": "product-card-image-unavailable", children: _jsx("span", { className: cn("bg-muted/45 block aspect-square w-full overflow-hidden", PRODUCT_CARD_IMAGE_RADIUS) }) }));
 };
 /**
  * The photograph itself, filling the frame `DraggableImage` insets - the
@@ -46,7 +47,7 @@ const ImageContent = ({ imageSrc, hoverImageSrc, showingInstallShot, productName
         productImageFade = showingInstallShot ? "opacity-0" : "";
         installImageFade = showingInstallShot ? "opacity-100" : "opacity-0";
     }
-    return (_jsx(Box, { className: "absolute inset-0 overflow-hidden", children: _jsxs(MediaFrame, { className: "size-full rounded-3xl @[180px]/product-card:rounded-2xl", children: [renderImage({
+    return (_jsx(Box, { className: "absolute inset-0 overflow-hidden", children: _jsxs(MediaFrame, { className: cn("size-full", PRODUCT_CARD_IMAGE_RADIUS), children: [renderImage({
                     alt: `${productName} - Product image`,
                     className: cn("object-cover", hasHoverImage && "duration-normal transition-opacity ease-out", hasHoverImage && productImageFade),
                     draggable: false,
@@ -89,11 +90,11 @@ const DraggableImage = ({ className, imageSrc, hoverImageSrc, variantName, showS
             scale: dragging ? 0.9 : 1,
             touchAction: "none",
             transition: "opacity 300ms ease-out, scale 300ms ease-out",
-        }, ...dragListeners, ...props, children: _jsxs(MediaFrame, { className: "@[180px]/product-card:bg-card relative aspect-square w-full rounded-3xl bg-gray-100 @[180px]/product-card:rounded-2xl", children: [_jsx(ImageContent, { hoverImageSrc: hoverImageSrc, imageSrc: imageSrc, showingInstallShot: showingInstallShot, priority: priority, productName: variantName, sizes: sizes }), shouldShowSimilarityScore ? (_jsx(Box, { className: "absolute right-2 bottom-2 z-10", children: _jsxs(Box, { as: "span", className: "glass-media text-micro rounded px-1.5 py-0.5 text-white/70", children: [(similarityScore * 100).toFixed(0), "%"] }) })) : null, _jsx(ProductCardAvailabilityStatus, {})] }) }));
+        }, ...dragListeners, ...props, children: _jsxs(MediaFrame, { className: cn("@[180px]/product-card:bg-card relative aspect-square w-full bg-gray-100", PRODUCT_CARD_IMAGE_RADIUS), children: [_jsx(ImageContent, { hoverImageSrc: hoverImageSrc, imageSrc: imageSrc, showingInstallShot: showingInstallShot, priority: priority, productName: variantName, sizes: sizes }), shouldShowSimilarityScore ? (_jsx(Box, { className: "absolute right-2 bottom-2 z-10", children: _jsxs(Box, { as: "span", className: "glass-media text-micro rounded px-1.5 py-0.5 text-white/70", children: [(similarityScore * 100).toFixed(0), "%"] }) })) : null, _jsx(ProductCardAvailabilityStatus, {})] }) }));
 };
 const SwatchImage = ({ className, dragListeners, imageSizes, isDragging, mainImage, priority, ref, ...props }) => {
     const { currentVariant, renderImage } = useProductCard();
-    return (_jsxs(Box, { className: cn("relative size-full overflow-hidden rounded-2xl bg-transparent", className), "data-component": "product-card-image", onClickCapture: (e) => {
+    return (_jsxs(Box, { className: cn("relative size-full overflow-hidden bg-transparent", PRODUCT_CARD_SWATCH_IMAGE_RADIUS, className), "data-component": "product-card-image", onClickCapture: (e) => {
             if (isDragging) {
                 e.preventDefault();
                 e.stopPropagation();

package/dist/compositions/product-card/product-card-radius.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The photograph's corner, concentric with the card's. Below 180px the
+ * photograph is the card and takes its corner; from 180px it sits 16px inside
+ * the card, so its corner is the card's less 16px (8px, then 20px once the card
+ * takes the 4xl corner at 240px).
+ */
+export declare const PRODUCT_CARD_IMAGE_RADIUS = "rounded-3xl @[180px]/product-card:rounded-[calc(var(--radius-3xl)_-_1rem)] @[240px]/product-card:rounded-[calc(var(--radius-4xl)_-_1rem)]";
+/** The swatch tile's photograph, 4px inside the tile's 3xl corner. */
+export declare const PRODUCT_CARD_SWATCH_IMAGE_RADIUS = "rounded-[calc(var(--radius-3xl)_-_0.25rem)]";

package/dist/compositions/product-card/product-card-radius.js

@@ -0,0 +1,9 @@
+/**
+ * The photograph's corner, concentric with the card's. Below 180px the
+ * photograph is the card and takes its corner; from 180px it sits 16px inside
+ * the card, so its corner is the card's less 16px (8px, then 20px once the card
+ * takes the 4xl corner at 240px).
+ */
+export const PRODUCT_CARD_IMAGE_RADIUS = "rounded-3xl @[180px]/product-card:rounded-[calc(var(--radius-3xl)_-_1rem)] @[240px]/product-card:rounded-[calc(var(--radius-4xl)_-_1rem)]";
+/** The swatch tile's photograph, 4px inside the tile's 3xl corner. */
+export const PRODUCT_CARD_SWATCH_IMAGE_RADIUS = "rounded-[calc(var(--radius-3xl)_-_0.25rem)]";

package/dist/compositions/product-card/product-card-root.d.ts

@@ -33,6 +33,8 @@ declare const ProductCardBase: ({ className, product, variantId, mode, width, ac
  * `linkAs={Link}` - the defaults are a plain `<img>` and `<a>`.
  * @bestPractice Cart UI renders only when a `renderAddToCart` slot is
  * provided; keep `dragAdapter` referentially stable (module-level constant).
+ * @bestPractice Use ProductCard for a material in a grid or list; its image is square, which is how a material is always shown. Don't rebuild the card with a landscape image.
+ * @keywords material card, material tile, sample card, catalogue card, product tile
  * @category catalogue
  */
 export declare const ProductCard: import("react").MemoExoticComponent<typeof ProductCardBase>;

package/dist/compositions/product-card/product-card-root.js

@@ -42,6 +42,8 @@ const ProductCardBase = ({ className, product, variantId, mode = "group", width,
  * `linkAs={Link}` - the defaults are a plain `<img>` and `<a>`.
  * @bestPractice Cart UI renders only when a `renderAddToCart` slot is
  * provided; keep `dragAdapter` referentially stable (module-level constant).
+ * @bestPractice Use ProductCard for a material in a grid or list; its image is square, which is how a material is always shown. Don't rebuild the card with a landscape image.
+ * @keywords material card, material tile, sample card, catalogue card, product tile
  * @category catalogue
  */
 export const ProductCard = memo(ProductCardBase);

package/dist/compositions/product-card/product-card-skeleton.js

@@ -3,6 +3,7 @@ import { Box } from "@instruments/materia-ui/components/box";
 import { Skeleton } from "@instruments/materia-ui/components/skeleton";
 import { HStack, VStack } from "@instruments/materia-ui/components/stack";
 import { cn } from "@instruments/materia-ui/utils/cn";
+import { PRODUCT_CARD_IMAGE_RADIUS } from "./product-card-radius.js";
 /** The fifth dot, which the card itself only shows from 240px up. */
 const SWATCH_PLACEHOLDERS = [0, 1, 2, 3, 4];
 const SwatchRow = () => (_jsx(HStack, { className: "min-h-5 gap-2.5", children: SWATCH_PLACEHOLDERS.map((index) => (_jsx(Skeleton, { className: cn("size-5 rounded-full", index === SWATCH_PLACEHOLDERS.length - 1 &&
@@ -29,4 +30,4 @@ const SwatchRow = () => (_jsx(HStack, { className: "min-h-5 gap-2.5", children:
  * misjudged the common case instead. A grid that turns either off on every
  * card passes the same flags here.
  */
-export const ProductCardSkeleton = ({ className, showAddToCart = true, showSwatches = true, style, }) => (_jsxs(Box, { className: cn("@container/product-card w-full", className), style: style, children: [_jsxs(VStack, { className: "flex @[180px]/product-card:hidden", gap: "none", children: [_jsx(Skeleton, { className: "aspect-square w-full rounded-3xl" }), _jsxs(VStack, { className: "gap-2.5 px-1.5 py-2", gap: "none", children: [_jsxs(VStack, { className: "gap-1 px-0.5", gap: "none", children: [_jsxs(VStack, { className: "gap-0.5", gap: "none", children: [_jsx(Skeleton, { className: "h-5 w-3/5" }), _jsx(Skeleton, { className: "h-4 w-4/5" })] }), _jsx(Skeleton, { className: "h-4 w-2/3" }), showSwatches ? _jsx(SwatchRow, {}) : null] }), showAddToCart ? (_jsx(Skeleton, { className: "h-9 w-full rounded-full" })) : null] })] }), _jsxs(VStack, { className: "bg-card hidden overflow-hidden rounded-3xl shadow-xs @[180px]/product-card:flex @[240px]/product-card:rounded-4xl", gap: "none", children: [_jsx(Box, { className: "w-full px-4 pt-4", children: _jsx(Skeleton, { className: "aspect-square w-full rounded-2xl", variant: "light" }) }), _jsx(VStack, { className: "pt-2 pb-4", gap: "none", children: _jsxs(VStack, { className: "gap-2.5 px-4 @[240px]/product-card:gap-4", gap: "none", children: [_jsxs(VStack, { className: "gap-1 px-0.5", gap: "none", children: [_jsxs(VStack, { gap: "none", children: [_jsx(Skeleton, { className: "h-5.5 w-3/5 rounded", variant: "light" }), _jsx(Skeleton, { className: "h-5 w-4/5 rounded", variant: "light" })] }), _jsx(Skeleton, { className: "h-4 w-2/3 rounded", variant: "light" }), showSwatches ? (_jsx(Box, { className: "pt-1", children: _jsx(SwatchRow, {}) })) : null] }), showAddToCart ? (_jsx(HStack, { children: _jsx(Skeleton, { className: "h-9 w-full rounded-full @[240px]/product-card:w-32", variant: "light" }) })) : null] }) })] })] }));
+export const ProductCardSkeleton = ({ className, showAddToCart = true, showSwatches = true, style, }) => (_jsxs(Box, { className: cn("@container/product-card w-full", className), style: style, children: [_jsxs(VStack, { className: "flex @[180px]/product-card:hidden", gap: "none", children: [_jsx(Skeleton, { className: "aspect-square w-full rounded-3xl" }), _jsxs(VStack, { className: "gap-2.5 px-1.5 py-2", gap: "none", children: [_jsxs(VStack, { className: "gap-1 px-0.5", gap: "none", children: [_jsxs(VStack, { className: "gap-0.5", gap: "none", children: [_jsx(Skeleton, { className: "h-5 w-3/5" }), _jsx(Skeleton, { className: "h-4 w-4/5" })] }), _jsx(Skeleton, { className: "h-4 w-2/3" }), showSwatches ? _jsx(SwatchRow, {}) : null] }), showAddToCart ? (_jsx(Skeleton, { className: "h-9 w-full rounded-full" })) : null] })] }), _jsxs(VStack, { className: "bg-card hidden overflow-hidden rounded-3xl shadow-xs @[180px]/product-card:flex @[240px]/product-card:rounded-4xl", gap: "none", children: [_jsx(Box, { className: "w-full px-4 pt-4", children: _jsx(Skeleton, { className: cn("aspect-square w-full", PRODUCT_CARD_IMAGE_RADIUS), variant: "light" }) }), _jsx(VStack, { className: "pt-2 pb-4", gap: "none", children: _jsxs(VStack, { className: "gap-2.5 px-4 @[240px]/product-card:gap-4", gap: "none", children: [_jsxs(VStack, { className: "gap-1 px-0.5", gap: "none", children: [_jsxs(VStack, { gap: "none", children: [_jsx(Skeleton, { className: "h-5.5 w-3/5 rounded", variant: "light" }), _jsx(Skeleton, { className: "h-5 w-4/5 rounded", variant: "light" })] }), _jsx(Skeleton, { className: "h-4 w-2/3 rounded", variant: "light" }), showSwatches ? (_jsx(Box, { className: "pt-1", children: _jsx(SwatchRow, {}) })) : null] }), showAddToCart ? (_jsx(HStack, { children: _jsx(Skeleton, { className: "h-9 w-full rounded-full @[240px]/product-card:w-32", variant: "light" }) })) : null] }) })] })] }));

package/dist/compositions/product-card/product-card-swatch.js

@@ -9,6 +9,7 @@ import { ProductCardImage } from "./product-card-image.js";
 import { ProductCardLink } from "./product-card-link.js";
 import { ProductCardProcessing } from "./product-card-processing.js";
 import { ProductCardQuickView } from "./product-card-quick-view.js";
+import { PRODUCT_CARD_SWATCH_IMAGE_RADIUS } from "./product-card-radius.js";
 import { ProductCardSwatchAdd } from "./product-card-swatch-add.js";
 const SwatchShell = ({ active, children, dragging, processing, }) => (_jsx(Box, { className: cn(
     // Bare at rest, so the tile reads as its image alone; the card surface
@@ -32,7 +33,7 @@ const SwatchCaption = () => {
 /** The square photograph with the add control and Quick view over it. */
 const SwatchMedia = ({ overrideImageUrl, priority, }) => {
     const { active, addGlyph, availability, currentVariant, dragging, labels, linkComponent, linkPrefetch, menuOpen, onAdd, onCardClick, onQuickView, processing, productUrl, } = useProductCard();
-    return (_jsxs(Box, { className: "relative aspect-square w-full overflow-hidden rounded-2xl", children: [_jsx(ProductCardLink, { blocked: availability === "blocked", className: "block size-full", href: productUrl, label: `View ${currentVariant.name}`, linkComponent: linkComponent, onActivate: onCardClick, prefetch: linkPrefetch, children: _jsx(ProductCardImage, { overrideImageUrl: overrideImageUrl, priority: priority }) }), dragging ? null : (_jsx(ProductCardSwatchAdd, { active: active, glyph: addGlyph, labels: labels, menuOpen: menuOpen, onAdd: onAdd })), dragging || processing !== undefined ? null : (_jsx(ProductCardQuickView, { align: "start", onQuickView: onQuickView }))] }));
+    return (_jsxs(Box, { className: cn("relative aspect-square w-full overflow-hidden", PRODUCT_CARD_SWATCH_IMAGE_RADIUS), children: [_jsx(ProductCardLink, { blocked: availability === "blocked", className: "block size-full", href: productUrl, label: `View ${currentVariant.name}`, linkComponent: linkComponent, onActivate: onCardClick, prefetch: linkPrefetch, children: _jsx(ProductCardImage, { overrideImageUrl: overrideImageUrl, priority: priority }) }), dragging ? null : (_jsx(ProductCardSwatchAdd, { active: active, glyph: addGlyph, labels: labels, menuOpen: menuOpen, onAdd: onAdd })), dragging || processing !== undefined ? null : (_jsx(ProductCardQuickView, { align: "start", onQuickView: onQuickView }))] }));
 };
 /**
  * ProductCardSwatch - the image-first tile for boards and canvases.

package/dist/data/docs-manifest.js

@@ -458,8 +458,8 @@ export const docsManifest = {
                             name: "ratio",
                             type: "number",
                             required: false,
-                            defaultValue: "16 / 9",
-                            description: "Desired width-to-height ratio, expressed as a single number (width / height).",
+                            defaultValue: "1",
+                            description: "Desired width-to-height ratio, expressed as a single number (width / height).\nSquare unless asked: a material is shown at 1:1, and only scenes and\nvideo take a wide ratio.",
                         },
                     ],
                 },
@@ -472,8 +472,16 @@ export const docsManifest = {
             bestPractices: [
                 "Give it exactly one child and let it fill - set the media to `size-full object-cover`; `AspectRatio` sizes to the available width and derives height from `ratio`.",
                 "Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.",
+                "Show a material, swatch or sample at the default 1:1 - never landscape. A sample is cut square, and a wide crop reads as room photography; set a wide `ratio` only for a scene, an interior or video.",
+            ],
+            keywords: [
+                "material image",
+                "swatch image",
+                "sample image",
+                "thumbnail",
+                "square",
+                "image ratio",
             ],
-            keywords: [],
             uses: [],
             usedBy: [],
             anatomy: {
@@ -6957,8 +6965,9 @@ export const docsManifest = {
                 "Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.",
                 "Set `edge` to frame photography with an inset hairline that stays above the media; do not fake it with a border or an inset shadow on the frame, which the media hides.",
                 "Reach for `raised` only when the frame sits on the same fill as its surface; in a dense row the edge already separates it.",
+                "Frame a material, swatch or sample square: give the frame `aspect-square` (or wrap it in `AspectRatio`, which defaults to 1:1). Never crop a material landscape.",
             ],
-            keywords: [],
+            keywords: ["material image", "product image", "photo frame", "thumbnail"],
             uses: [],
             usedBy: ["editorial-card", "product-card"],
         },
@@ -11704,8 +11713,15 @@ export const docsManifest = {
                 "Feed fills through `color`/`background`/`colors`, never a hex in `className`/`style` - the props drive the contrast-aware text colour, selection ring, and darkening overlay.",
                 "Reach for `Swatch` for a selectable colour/gradient/material chip or tile; a tiny non-interactive status marker is `Dot`, and a display-only status/category label is `Badge`.",
                 "For a gradient or image chip fill pass `light` - auto contrast detection (`isLightColor`) only reads solid colours, so overlaid icons/labels lose legibility without it.",
+                "A material swatch is always square, as Swatch draws it; never stretch a tile into a landscape crop, and in a grid let the column set the size.",
+            ],
+            keywords: [
+                "material swatch",
+                "material sample",
+                "finish",
+                "colourway",
+                "colour chip",
             ],
-            keywords: [],
             uses: ["center", "flex", "icon"],
             usedBy: [
                 "swatch-fan",
@@ -19657,10 +19673,17 @@ export const docsManifest = {
             bestPractices: [
                 "In Next.js apps pass `renderImage` wrapping `next/image` and\n`linkAs={Link}` - the defaults are a plain `<img>` and `<a>`.",
                 "Cart UI renders only when a `renderAddToCart` slot is\nprovided; keep `dragAdapter` referentially stable (module-level constant).",
+                "Use ProductCard for a material in a grid or list; its image is square, which is how a material is always shown. Don't rebuild the card with a landscape image.",
                 "Pass `renderImage` wrapping `next/image` in Next.js apps -\nthe default renderer is a plain `<img>` and skips Next's optimisation.",
                 "Keep `dragAdapter` referentially stable (a module-level\nconstant) - an inline factory remounts the image subtree and drops the\ndrag ref mid-drag.",
             ],
-            keywords: [],
+            keywords: [
+                "material card",
+                "material tile",
+                "sample card",
+                "catalogue card",
+                "product tile",
+            ],
             uses: [
                 "badge",
                 "box",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materia-ui",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Materia design system: React components, tokens and Tailwind v4 styles.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -898,6 +898,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/finish-dist.ts",
     "deploy:figma-connect": "tsx figma/connect-templates.ts --publish",
+    "deploy:figma-descriptions": "tsx figma/descriptions.ts push",
     "deploy:figma-storybook-links": "tsx figma/storybook-links.ts --publish",
     "deploy:figma-tokens": "tsx figma/deploy-tokens.ts",
     "generate:agent-docs": "node scripts/generate-agent-docs.ts",