@instructure/ui-card 0.0.0-stage → 11.7.9

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## [11.7.9](https://github.com/instructure/instructure-ui/compare/v11.7.8...v11.7.9) (2026-10-13)
+
+### Features
+
+* **ui-card:** add Card component with base and nested variants ([#2743](https://github.com/instructure/instructure-ui/issues/2743)) ([2b652ea](https://github.com/instructure/instructure-ui/commit/2b652ea90c73805905ebb6302c45c52aa2d7f69a))

package/LICENSE.md

@@ -0,0 +1,28 @@
+---
+title: The MIT License (MIT)
+category: Getting Started
+order: 9
+isWIP: true
+---
+
+# The MIT License (MIT)
+
+Copyright (c) 2015 Instructure, Inc.
+
+**Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions.**
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+## ui-card
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm][npm]][npm-url]
+[![MIT License][license-badge]][license]
+[![Code of Conduct][coc-badge]][coc]
+
+### Components
+
+The `ui-card` package contains the following:
+
+- Card
+
+### Installation
+
+```sh
+npm install @instructure/ui-card
+```
+
+[npm]: https://img.shields.io/npm/v/@instructure/ui-card.svg
+[npm-url]: https://npmjs.com/package/@instructure/ui-card
+[license-badge]: https://img.shields.io/npm/l/instructure-ui.svg?style=flat-square
+[license]: https://github.com/instructure/instructure-ui/blob/master/LICENSE.md
+[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
+[coc]: https://github.com/instructure/instructure-ui/blob/master/CODE_OF_CONDUCT.md

package/es/Card/v1/index.js

@@ -0,0 +1,59 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { useStyleNew } from '@instructure/emotion';
+import { passthroughProps } from '@instructure/ui-react-utils';
+import generateStyle from './styles.js';
+
+/**
+---
+category: components/Cards
+---
+**/
+import { jsx as _jsx } from "@emotion/react/jsx-runtime";
+const Card = ({
+  children,
+  variant = 'base',
+  themeOverride,
+  ...rest
+}) => {
+  const styles = useStyleNew({
+    generateStyle,
+    themeOverride,
+    params: {
+      variant
+    },
+    componentId: 'Card',
+    displayName: 'Card'
+  });
+  return _jsx("div", {
+    ...passthroughProps(rest),
+    css: styles?.card,
+    children: _jsx("div", {
+      css: styles?.content,
+      children: children
+    })
+  });
+};
+export default Card;
+export { Card };

package/es/Card/v1/props.js

@@ -0,0 +1,26 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+const allowedProps = ['children', 'variant'];
+export { allowedProps };

package/es/Card/v1/styles.js

@@ -0,0 +1,99 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { boxShadowObjectsToCSSString } from '@instructure/ui-themes';
+/**
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param componentTheme The theme variable object.
+ * @param props the props of the component, the style is applied to
+ * @return The final style object, which will be used in the component
+ */
+const generateStyle = (componentTheme, props) => {
+  const {
+    variant
+  } = props;
+  const variantSizeStyles = {
+    base: {
+      sm: {
+        borderRadius: componentTheme.borderRadiusBaseSm,
+        padding: componentTheme.paddingBaseSm
+      },
+      md: {
+        borderRadius: componentTheme.borderRadiusBaseMd,
+        padding: componentTheme.paddingBaseMd
+      },
+      lg: {
+        borderRadius: componentTheme.borderRadiusBaseLg,
+        padding: componentTheme.paddingBaseLg
+      }
+    },
+    nested: {
+      sm: {
+        borderRadius: componentTheme.borderRadiusNestedSm,
+        padding: componentTheme.paddingNestedSm
+      },
+      md: {
+        borderRadius: componentTheme.borderRadiusNestedMd,
+        padding: componentTheme.paddingNestedMd
+      },
+      lg: {
+        borderRadius: componentTheme.borderRadiusNestedLg,
+        padding: componentTheme.paddingNestedLg
+      }
+    }
+  };
+  const variantVariants = {
+    base: {
+      background: componentTheme.backgroundColor,
+      boxShadow: boxShadowObjectsToCSSString(componentTheme.boxShadow)
+    },
+    nested: {
+      border: `1px solid ${componentTheme.nestedBorderColor}`
+    }
+  };
+  return {
+    card: {
+      label: 'card',
+      containerType: 'inline-size',
+      width: '100%'
+    },
+    content: {
+      overflowWrap: 'anywhere',
+      ...variantVariants[variant],
+      [`@container (width < ${componentTheme.breakpointMd})`]: {
+        ...variantSizeStyles[variant]?.sm
+      },
+      [`@container ((width >= ${componentTheme.breakpointMd}) and (width < ${componentTheme.breakpointLg}))`]: {
+        ...variantSizeStyles[variant]?.md
+      },
+      [`@container (width >= ${componentTheme.breakpointLg})`]: {
+        ...variantSizeStyles[variant]?.lg
+      }
+    }
+  };
+};
+export default generateStyle;

package/es/exports/a.js

@@ -0,0 +1,24 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+export { Card } from '../Card/v1/index.js';

package/lib/Card/v1/index.js

@@ -0,0 +1,65 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.Card = void 0;
+var _emotion = require("@instructure/emotion");
+var _uiReactUtils = require("@instructure/ui-react-utils");
+var _styles = _interopRequireDefault(require("./styles.js"));
+var _jsxRuntime = require("@emotion/react/jsx-runtime");
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+---
+category: components/Cards
+---
+**/const Card = ({
+  children,
+  variant = 'base',
+  themeOverride,
+  ...rest
+}) => {
+  const styles = (0, _emotion.useStyleNew)({
+    generateStyle: _styles.default,
+    themeOverride,
+    params: {
+      variant
+    },
+    componentId: 'Card',
+    displayName: 'Card'
+  });
+  return (0, _jsxRuntime.jsx)("div", {
+    ...(0, _uiReactUtils.passthroughProps)(rest),
+    css: styles?.card,
+    children: (0, _jsxRuntime.jsx)("div", {
+      css: styles?.content,
+      children: children
+    })
+  });
+};
+exports.Card = Card;
+var _default = exports.default = Card;

package/lib/Card/v1/props.js

@@ -0,0 +1,31 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.allowedProps = void 0;
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+const allowedProps = exports.allowedProps = ['children', 'variant'];

package/lib/Card/v1/styles.js

@@ -0,0 +1,105 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _uiThemes = require("@instructure/ui-themes");
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param componentTheme The theme variable object.
+ * @param props the props of the component, the style is applied to
+ * @return The final style object, which will be used in the component
+ */
+const generateStyle = (componentTheme, props) => {
+  const {
+    variant
+  } = props;
+  const variantSizeStyles = {
+    base: {
+      sm: {
+        borderRadius: componentTheme.borderRadiusBaseSm,
+        padding: componentTheme.paddingBaseSm
+      },
+      md: {
+        borderRadius: componentTheme.borderRadiusBaseMd,
+        padding: componentTheme.paddingBaseMd
+      },
+      lg: {
+        borderRadius: componentTheme.borderRadiusBaseLg,
+        padding: componentTheme.paddingBaseLg
+      }
+    },
+    nested: {
+      sm: {
+        borderRadius: componentTheme.borderRadiusNestedSm,
+        padding: componentTheme.paddingNestedSm
+      },
+      md: {
+        borderRadius: componentTheme.borderRadiusNestedMd,
+        padding: componentTheme.paddingNestedMd
+      },
+      lg: {
+        borderRadius: componentTheme.borderRadiusNestedLg,
+        padding: componentTheme.paddingNestedLg
+      }
+    }
+  };
+  const variantVariants = {
+    base: {
+      background: componentTheme.backgroundColor,
+      boxShadow: (0, _uiThemes.boxShadowObjectsToCSSString)(componentTheme.boxShadow)
+    },
+    nested: {
+      border: `1px solid ${componentTheme.nestedBorderColor}`
+    }
+  };
+  return {
+    card: {
+      label: 'card',
+      containerType: 'inline-size',
+      width: '100%'
+    },
+    content: {
+      overflowWrap: 'anywhere',
+      ...variantVariants[variant],
+      [`@container (width < ${componentTheme.breakpointMd})`]: {
+        ...variantSizeStyles[variant]?.sm
+      },
+      [`@container ((width >= ${componentTheme.breakpointMd}) and (width < ${componentTheme.breakpointLg}))`]: {
+        ...variantSizeStyles[variant]?.md
+      },
+      [`@container (width >= ${componentTheme.breakpointLg})`]: {
+        ...variantSizeStyles[variant]?.lg
+      }
+    }
+  };
+};
+var _default = exports.default = generateStyle;

package/lib/exports/a.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "Card", {
+  enumerable: true,
+  get: function () {
+    return _index.Card;
+  }
+});
+var _index = require("../Card/v1/index.js");

package/lib/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@instructure/ui-card",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "11.7.9",
+  "description": "A basic wrapper component for grouping content with padding, border radius, shadow, and background.",
+  "author": "Instructure, Inc. Engineering and Product Design",
+  "module": "./es/index.js",
+  "main": "./lib/index.js",
+  "types": "./types/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/instructure/instructure-ui.git"
+  },
+  "homepage": "https://instructure.github.io/instructure-ui/",
+  "bugs": "https://github.com/instructure/instructure-ui/issues",
+  "license": "MIT",
+  "dependencies": {
+    "@babel/runtime": "^7.29.7",
+    "@instructure/emotion": "11.7.9",
+    "@instructure/shared-types": "11.7.9",
+    "@instructure/ui-react-utils": "11.7.9",
+    "@instructure/ui-themes": "11.7.9"
+  },
+  "devDependencies": {
+    "@instructure/ui-axe-check": "11.7.9",
+    "@instructure/ui-babel-preset": "11.7.9",
+    "vitest": "^5.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18 <=19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./lib/*": "./lib/*",
+    "./es/*": "./es/*",
+    "./types/*": "./types/*",
+    "./package.json": "./package.json",
+    "./src/*": "./src/*",
+    ".": {
+      "src": "./src/exports/a.ts",
+      "types": "./types/exports/a.d.ts",
+      "import": "./es/exports/a.js",
+      "require": "./lib/exports/a.js",
+      "default": "./es/exports/a.js"
+    },
+    "./v11_7": {
+      "src": "./src/exports/a.ts",
+      "types": "./types/exports/a.d.ts",
+      "import": "./es/exports/a.js",
+      "require": "./lib/exports/a.js",
+      "default": "./es/exports/a.js"
+    },
+    "./latest": {
+      "src": "./src/exports/a.ts",
+      "types": "./types/exports/a.d.ts",
+      "import": "./es/exports/a.js",
+      "require": "./lib/exports/a.js",
+      "default": "./es/exports/a.js"
+    }
+  },
+  "scripts": {
+    "lint": "ui-scripts lint",
+    "lint:fix": "ui-scripts lint --fix",
+    "clean": "ui-scripts clean",
+    "build": "ui-scripts build --modules es,cjs",
+    "build:watch": "pnpm run ts:check -- --watch & ui-scripts build --watch",
+    "build:types": "tsc -p tsconfig.build.json",
+    "ts:check": "tsc -p tsconfig.build.json --noEmit --emitDeclarationOnly false"
+  }
 }

package/src/Card/v1/README.md

@@ -0,0 +1,105 @@
+---
+describes: Card
+---
+
+Use `<Card />` as a basic wrapper for grouping related content with padding,
+border radius, shadow, and background color.
+
+Card has two internal width breakpoints. It measures its own rendered width and scales its
+padding and border radius from that, so the same markup works in a narrow
+sidebar and in a wide main region.
+
+```js
+---
+type: example
+---
+<Card>
+  <Heading level="h3" margin="0 0 x-small 0">
+    Base card
+  </Heading>
+  <Text variant="content">Content goes here.</Text>
+</Card>
+```
+
+### Variants
+
+`variant` picks the surface treatment:
+
+- `base` _(default)_ draws a background color and a shadow. Use it for a Card
+  that sits on the page background.
+- `nested` draws a thin border and no background or shadow. Use it inside a
+  `base` Card.
+
+```js
+---
+type: example
+---
+<Card variant="base">
+  <Heading level="h3" margin="0 0 x-small 0">
+    Base card
+  </Heading>
+  <Text variant="content">Draws a background color and a shadow.</Text>
+  <Card variant="nested">
+    <Heading level="h4" margin="0 0 x-small 0">
+      Nested card
+    </Heading>
+    <Text variant="content">
+      Draws a border and borrows the surface behind it.
+    </Text>
+  </Card>
+</Card>
+```
+
+### Responsive padding and border radius
+
+The `Card`'s width always fills the container. It will set its own padding and border radius responsively, depending on its own width. Use responsive containers (like flex or grid) to build responsive layouts with `Card`
+Drag the right edge of the panel below to watch the steps change.
+
+```js
+---
+type: example
+---
+<div
+  style={{
+    resize: 'horizontal',
+    overflow: 'auto',
+    minWidth: '10rem',
+    maxWidth: '100%',
+    border: '1px dashed #999',
+    padding: '0.5rem'
+  }}
+>
+  <Card>
+    <Text variant="content">
+      Drag this panel's right edge to see padding and border radius change.
+    </Text>
+  </Card>
+</div>
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="yes" title="Do">
+    <Figure.Item>
+      Place a <code>nested</code> Card inside a <code>base</code> Card
+    </Figure.Item>
+    <Figure.Item>
+      Use a flex or grid layout when placing several <code>nested</code> Cards
+      side by side, so they can reflow to fit the available width
+    </Figure.Item>
+  </Figure>
+  <Figure recommendation="no" title="Don't">
+    <Figure.Item>
+      Place a <code>base</code> Card inside another <code>base</code> Card
+    </Figure.Item>
+    <Figure.Item>
+      Place a <code>nested</code> Card outside of a <code>base</code> Card
+    </Figure.Item>
+  </Figure>
+</Guidelines>
+```