@instruments/materia-ui 0.4.5 → 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-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/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.5",
+  "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",