@roadlittledawn/docs-design-system-react 0.11.1 → 0.12.0

package/USAGE.md

@@ -132,32 +132,59 @@ import { Card } from "@roadlittledawn/docs-design-system-react";
 | `titleColor` | `"blue" \| "green" \| "purple" \| "red" \| "yellow" \| "gray"` | `"gray"` | Color of the title text |
 | `backgroundColor` | `"blue" \| "green" \| "purple" \| "red" \| "yellow" \| "gray" \| "white"` | `"white"` | Background color of the card |
 | `href` | `string` | — | Optional link URL. When provided, the entire card becomes clickable |
+| `icon` | `ReactNode` | — | Optional icon to display. Pass a rendered icon component. In MDX, the consuming site's component map resolves string names to rendered components before passing here. |
+| `iconPlacement` | `"left" \| "top-left" \| "top-center"` | `"top-left"` | Where to place the icon: vertically centered on the left, above content flush left, or above content centered |
+| `showArrow` | `boolean` | `false` | Show an animated arrow in the lower-right corner to signal the card is navigable. Best used with `href`. |
 | `children` | `ReactNode` | — | Card content |
 | `className` | `string` | `""` | Additional CSS classes |
 
 ### Examples
 
 ```tsx
-{
-  /* Basic card */
-}
+{/* Basic card */}
 <Card title="Getting Started">
   Learn the basics of using this documentation system.
-</Card>;
+</Card>
 
-{
-  /* Clickable card */
-}
-<Card title="API Reference" href="/docs/api">
-  Complete reference for all available components.
-</Card>;
+{/* Clickable card with animated arrow */}
+<Card title="Get Started" href="/docs/quickstart" showArrow>
+  Follow the quickstart guide to set up in minutes.
+</Card>
 
-{
-  /* Colored background */
-}
+{/* Card with icon left (vertically centered beside content) */}
+<Card title="Documentation" icon={<YourIcon />} iconPlacement="left">
+  Read guides, tutorials, and API references.
+</Card>
+
+{/* Card with icon top-center */}
+<Card title="Documentation" icon={<YourIcon />} iconPlacement="top-center">
+  Read guides, tutorials, and API references.
+</Card>
+
+{/* Colored background */}
 <Card title="New Feature" titleColor="blue" backgroundColor="blue">
   Check out our latest component additions.
-</Card>;
+</Card>
+```
+
+### Icon usage in MDX
+
+In MDX files the `icon` prop is typically a string name (`icon="book"`). The consuming site's MDX component map is responsible for resolving strings to rendered icon components:
+
+```tsx
+// In your MDX components config:
+import { YourBookIcon, YourRocketIcon } from 'your-icon-library';
+
+const iconMap: Record<string, React.ComponentType> = {
+  book: YourBookIcon,
+  rocket: YourRocketIcon,
+};
+
+// Wrap Card in your MDX components map:
+Card: ({ icon, ...props }) => {
+  const IconComp = typeof icon === 'string' ? iconMap[icon] : null;
+  return <DdsCard icon={IconComp ? <IconComp /> : icon} {...props} />;
+}
 ```
 
 ---

package/dist/components/Card.d.ts

@@ -14,9 +14,29 @@ export interface CardProps {
     backgroundColor?: "blue" | "green" | "purple" | "red" | "yellow" | "gray" | "white";
     /** Optional link URL. When provided, the entire card becomes clickable */
     href?: string;
+    /**
+     * Optional icon to display. Pass a rendered icon component (e.g. `<YourIcon />`).
+     * In MDX, the consuming site's component map resolves icon name strings to rendered
+     * components before passing them here.
+     */
+    icon?: ReactNode;
+    /**
+     * Placement of the icon within the card.
+     * - `"left"` — icon centered vertically on the left, title + content on the right
+     * - `"top-left"` — icon above title and content, flush left
+     * - `"top-center"` — icon above title and content, horizontally centered
+     * @default 'top-left'
+     */
+    iconPlacement?: "left" | "top-left" | "top-center";
+    /**
+     * Show an animated arrow in the lower-right corner to signal the card is navigable.
+     * Best used together with `href`. The arrow animates with a springy motion on hover.
+     * @default false
+     */
+    showArrow?: boolean;
     /** Card content */
     children: ReactNode;
     /** Additional CSS classes */
     className?: string;
 }
-export declare function Card({ title, titleColor, backgroundColor, href, children, className, }: CardProps): import("react/jsx-runtime").JSX.Element;
+export declare function Card({ title, titleColor, backgroundColor, href, icon, iconPlacement, showArrow, children, className, }: CardProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Card.js

@@ -1,10 +1,11 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 export function Card(_a) {
-    var title = _a.title, _b = _a.titleColor, titleColor = _b === void 0 ? "gray" : _b, _c = _a.backgroundColor, backgroundColor = _c === void 0 ? "white" : _c, href = _a.href, children = _a.children, _d = _a.className, className = _d === void 0 ? "" : _d;
+    var title = _a.title, _b = _a.titleColor, titleColor = _b === void 0 ? "gray" : _b, _c = _a.backgroundColor, backgroundColor = _c === void 0 ? "white" : _c, href = _a.href, icon = _a.icon, _d = _a.iconPlacement, iconPlacement = _d === void 0 ? "top-left" : _d, _e = _a.showArrow, showArrow = _e === void 0 ? false : _e, children = _a.children, _f = _a.className, className = _f === void 0 ? "" : _f;
     var cardClasses = [
         "dds-card",
         "dds-card-bg-".concat(backgroundColor),
         href ? "dds-card-clickable" : "",
+        showArrow ? "dds-card-has-arrow" : "",
         className,
     ]
         .filter(Boolean)
@@ -13,7 +14,15 @@ export function Card(_a) {
     var textClasses = backgroundColor !== "white"
         ? "dds-card-text-".concat(backgroundColor)
         : "dds-card-text-gray";
-    var content = (_jsxs("div", { className: cardClasses, children: [title && _jsx("h3", { className: titleClasses, children: title }), _jsx("div", { className: textClasses, children: children })] }));
+    var iconEl = icon ? (_jsx("span", { className: [
+            "dds-card-icon",
+            iconPlacement === "top-center" ? "dds-card-icon-top-center" : "",
+        ]
+            .filter(Boolean)
+            .join(" "), "aria-hidden": "true", children: icon })) : null;
+    var arrowEl = showArrow ? (_jsx("span", { className: "dds-card-arrow", "aria-hidden": "true", children: _jsx("svg", { width: "16", height: "16", viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", children: _jsx("path", { d: "M2 8H14M10 4L14 8L10 12", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round" }) }) })) : null;
+    var bodyContent = icon && iconPlacement === "left" ? (_jsxs("div", { className: "dds-card-icon-row", children: [iconEl, _jsxs("div", { className: "dds-card-icon-content", children: [title && _jsx("h3", { className: titleClasses, children: title }), _jsx("div", { className: textClasses, children: children })] })] })) : (_jsxs(_Fragment, { children: [iconEl, title && _jsx("h3", { className: titleClasses, children: title }), _jsx("div", { className: textClasses, children: children })] }));
+    var content = (_jsxs("div", { className: cardClasses, children: [bodyContent, arrowEl] }));
     if (href) {
         return (_jsx("a", { href: href, className: "no-text-decoration", children: content }));
     }

package/dist/components/Card.stories.d.ts

@@ -14,6 +14,26 @@ export declare const Basic: Story;
  * Clickable card that links to another page.
  */
 export declare const Clickable: Story;
+/**
+ * Clickable card with an animated arrow in the lower-right corner. Hover to see the animation.
+ */
+export declare const WithArrow: Story;
+/**
+ * Card with an icon placed to the left, vertically centered next to the title and content.
+ */
+export declare const WithIconLeft: Story;
+/**
+ * Card with an icon placed above the title, flush left (the default top placement).
+ */
+export declare const WithIconTopLeft: Story;
+/**
+ * Card with an icon centered horizontally above the title and content.
+ */
+export declare const WithIconTopCenter: Story;
+/**
+ * Clickable card combining a left icon and the animated arrow. Hover to see the arrow animate.
+ */
+export declare const WithIconAndArrow: Story;
 /**
  * Card with colored background.
  */
@@ -22,6 +42,10 @@ export declare const ColoredBackground: Story;
  * Card without a title.
  */
 export declare const NoTitle: Story;
+/**
+ * All icon placement variants side by side.
+ */
+export declare const IconPlacements: Story;
 /**
  * All title color variants.
  */

package/dist/components/Card.stories.js

@@ -28,6 +28,21 @@ var meta = {
             control: 'text',
             description: 'Optional link URL. When provided, the entire card becomes clickable.',
         },
+        icon: {
+            control: false,
+            description: 'Optional icon to display. Pass a rendered icon component.',
+        },
+        iconPlacement: {
+            control: { type: 'select' },
+            options: ['left', 'top-left', 'top-center'],
+            description: 'Placement of the icon within the card.',
+            table: { defaultValue: { summary: "'top-left'" } },
+        },
+        showArrow: {
+            control: 'boolean',
+            description: 'Show an animated arrow in the lower-right corner to signal the card is navigable.',
+            table: { defaultValue: { summary: 'false' } },
+        },
         children: {
             control: 'text',
             description: 'Card content.',
@@ -41,12 +56,14 @@ var meta = {
     parameters: {
         docs: {
             description: {
-                component: "\nThe Card component provides a flexible container for displaying content with visual hierarchy.\n\n## When to Use\n\n- To group related content together\n- To create clickable navigation elements\n- To display feature highlights or key information\n- To organize content in grid layouts\n\n## When Not to Use\n\n- For plain text content (use typography components)\n- For alerts or notifications (use Callout)\n- For extensive content (consider using sections or pages)\n\n## Accessibility\n\n- Clickable cards use proper link semantics\n- Color is not the only means of conveying information\n        ",
+                component: "\nThe Card component provides a flexible container for displaying content with visual hierarchy.\n\n## When to Use\n\n- To group related content together\n- To create clickable navigation elements (use `href` + `showArrow`)\n- To display feature highlights with icons\n- To organize content in grid layouts\n\n## When Not to Use\n\n- For plain text content (use typography components)\n- For alerts or notifications (use Callout)\n- For extensive content (consider using sections or pages)\n\n## Icon Usage in MDX\n\nIn MDX files, `icon` is typically a string name (e.g. `icon=\"book\"`). The consuming site's\nMDX component map resolves the string to a rendered icon before passing it to Card:\n\n```tsx\n// In your MDX components config:\nCard: ({ icon, ...props }) => {\n  const IconComp = typeof icon === 'string' ? iconMap[icon] : null;\n  return <DdsCard icon={IconComp ? <IconComp /> : icon} {...props} />;\n}\n```\n\n## Accessibility\n\n- Clickable cards use proper link semantics\n- The arrow and icon are decorative (`aria-hidden`) and do not affect screen reader output\n- Color is not the only means of conveying information\n        ",
             },
         },
     },
 };
 export default meta;
+/** A simple inline SVG used in stories to simulate a real icon component. */
+var DemoIcon = function () { return (_jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: "M12 6.042A8.967 8.967 0 0 0 6 3.75c-1.052 0-2.062.18-3 .512v14.25A8.987 8.987 0 0 1 6 18c2.305 0 4.408.867 6 2.292m0-14.25a8.966 8.966 0 0 1 6-2.292c1.052 0 2.062.18 3 .512v14.25A8.987 8.987 0 0 0 18 18a8.967 8.967 0 0 0-6 2.292m0-14.25v14.25" }) })); };
 /**
  * Basic card with title and content.
  */
@@ -80,6 +97,98 @@ export var Clickable = {
         },
     },
 };
+/**
+ * Clickable card with an animated arrow in the lower-right corner. Hover to see the animation.
+ */
+export var WithArrow = {
+    args: {
+        title: 'Get Started',
+        href: '/docs/quickstart',
+        showArrow: true,
+        children: 'Follow the quickstart guide to set up in minutes.',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Card title=\"Get Started\" href=\"/docs/quickstart\" showArrow>\n  Follow the quickstart guide to set up in minutes.\n</Card>",
+            },
+        },
+    },
+};
+/**
+ * Card with an icon placed to the left, vertically centered next to the title and content.
+ */
+export var WithIconLeft = {
+    args: {
+        title: 'Documentation',
+        icon: _jsx(DemoIcon, {}),
+        iconPlacement: 'left',
+        children: 'Read guides, tutorials, and API references.',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "// In MDX the consuming site resolves the icon string to a component:\n<Card title=\"Documentation\" icon={<DemoIcon />} iconPlacement=\"left\">\n  Read guides, tutorials, and API references.\n</Card>",
+            },
+        },
+    },
+};
+/**
+ * Card with an icon placed above the title, flush left (the default top placement).
+ */
+export var WithIconTopLeft = {
+    args: {
+        title: 'Documentation',
+        icon: _jsx(DemoIcon, {}),
+        iconPlacement: 'top-left',
+        children: 'Read guides, tutorials, and API references.',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Card title=\"Documentation\" icon={<DemoIcon />} iconPlacement=\"top-left\">\n  Read guides, tutorials, and API references.\n</Card>",
+            },
+        },
+    },
+};
+/**
+ * Card with an icon centered horizontally above the title and content.
+ */
+export var WithIconTopCenter = {
+    args: {
+        title: 'Documentation',
+        icon: _jsx(DemoIcon, {}),
+        iconPlacement: 'top-center',
+        children: 'Read guides, tutorials, and API references.',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Card title=\"Documentation\" icon={<DemoIcon />} iconPlacement=\"top-center\">\n  Read guides, tutorials, and API references.\n</Card>",
+            },
+        },
+    },
+};
+/**
+ * Clickable card combining a left icon and the animated arrow. Hover to see the arrow animate.
+ */
+export var WithIconAndArrow = {
+    args: {
+        title: 'Get Started',
+        href: '/docs/quickstart',
+        icon: _jsx(DemoIcon, {}),
+        iconPlacement: 'left',
+        showArrow: true,
+        children: 'Follow the quickstart guide to set up in minutes.',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Card title=\"Get Started\" href=\"/docs/quickstart\" icon={<DemoIcon />} iconPlacement=\"left\" showArrow>\n  Follow the quickstart guide to set up in minutes.\n</Card>",
+            },
+        },
+    },
+};
 /**
  * Card with colored background.
  */
@@ -113,6 +222,19 @@ export var NoTitle = {
         },
     },
 };
+/**
+ * All icon placement variants side by side.
+ */
+export var IconPlacements = {
+    parameters: {
+        docs: {
+            source: {
+                code: "<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>\n  <Card title=\"Icon Left\" icon={<DemoIcon />} iconPlacement=\"left\">\n    Icon is centered vertically beside the content.\n  </Card>\n  <Card title=\"Icon Top Left\" icon={<DemoIcon />} iconPlacement=\"top-left\">\n    Icon sits above the title, flush left.\n  </Card>\n  <Card title=\"Icon Top Center\" icon={<DemoIcon />} iconPlacement=\"top-center\">\n    Icon sits above the title, horizontally centered.\n  </Card>\n</div>",
+            },
+        },
+    },
+    render: function () { return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: '1rem' }, children: [_jsx(Card, { title: "Icon Left", icon: _jsx(DemoIcon, {}), iconPlacement: "left", children: _jsx("span", { style: { color: 'var(--dds-card-text-gray)' }, children: "Icon is centered vertically beside the content." }) }), _jsx(Card, { title: "Icon Top Left", icon: _jsx(DemoIcon, {}), iconPlacement: "top-left", children: _jsx("span", { style: { color: 'var(--dds-card-text-gray)' }, children: "Icon sits above the title, flush left." }) }), _jsx(Card, { title: "Icon Top Center", icon: _jsx(DemoIcon, {}), iconPlacement: "top-center", children: _jsx("span", { style: { color: 'var(--dds-card-text-gray)' }, children: "Icon sits above the title, horizontally centered." }) })] })); },
+};
 /**
  * All title color variants.
  */

package/dist/styles.css

@@ -45,6 +45,13 @@
   --dds-card-text-yellow: #854d0e; /* yellow-800 */
   --dds-card-text-gray: #374151; /* gray-700 */
 
+  --dds-card-icon-size: 1.5rem; /* 24px */
+  --dds-card-icon-color: #6b7280; /* gray-500 */
+  --dds-card-icon-margin-bottom: 0.75rem;
+  --dds-card-icon-gap: 1rem;
+  --dds-card-arrow-color: #9ca3af; /* gray-400 */
+  --dds-card-arrow-inset: 0.75rem;
+
   /* Typography - Font Sizes */
   --dds-heading-1-size: 2.25rem; /* text-4xl */
   --dds-heading-2-size: 1.875rem; /* text-3xl */
@@ -359,6 +366,9 @@
   --dds-card-text-yellow: #fef08a; /* yellow-200 */
   --dds-card-text-gray: #d1d5db; /* gray-300 */
 
+  --dds-card-icon-color: #9ca3af; /* gray-400 */
+  --dds-card-arrow-color: #6b7280; /* gray-500 */
+
   /* Link */
   --dds-link-color: #60a5fa; /* blue-400 */
   --dds-link-color-hover: #93c5fd; /* blue-300 */
@@ -541,6 +551,9 @@
     --dds-card-text-yellow: #fef08a;
     --dds-card-text-gray: #d1d5db;
 
+    --dds-card-icon-color: #9ca3af; /* gray-400 */
+    --dds-card-arrow-color: #6b7280; /* gray-500 */
+
     /* Link */
     --dds-link-color: #60a5fa;
     --dds-link-color-hover: #93c5fd;
@@ -723,6 +736,9 @@
   --dds-card-text-yellow: #fef08a;
   --dds-card-text-gray: #d1d5db;
 
+  --dds-card-icon-color: #9ca3af; /* gray-400 */
+  --dds-card-arrow-color: #6b7280; /* gray-500 */
+
   /* Link */
   --dds-link-color: #60a5fa;
   --dds-link-color-hover: #93c5fd;
@@ -1085,6 +1101,7 @@ a.no-text-decoration {
   padding: var(--dds-card-padding);
   border-radius: var(--dds-card-radius);
   border: 1px solid var(--dds-card-border);
+  position: relative;
 }
 .dds-card-clickable {
   cursor: pointer;
@@ -1143,6 +1160,77 @@ a.no-text-decoration {
 .dds-card-title-gray {
   color: var(--dds-card-title-gray);
 }
+/* Icon */
+.dds-card-icon {
+  display: block;
+  width: var(--dds-card-icon-size);
+  height: var(--dds-card-icon-size);
+  color: var(--dds-card-icon-color);
+  flex-shrink: 0;
+  margin-bottom: var(--dds-card-icon-margin-bottom);
+}
+.dds-card-icon > * {
+  width: 100%;
+  height: 100%;
+}
+.dds-card-icon-top-center {
+  margin-left: auto;
+  margin-right: auto;
+}
+/* Icon-left layout */
+.dds-card-icon-row {
+  display: flex;
+  align-items: center;
+  gap: var(--dds-card-icon-gap);
+}
+.dds-card-icon-row .dds-card-icon {
+  margin-bottom: 0;
+}
+.dds-card-icon-content {
+  flex: 1;
+  min-width: 0;
+}
+/* Arrow */
+.dds-card-has-arrow {
+  padding-right: calc(var(--dds-card-padding) + 1.25rem);
+}
+[dir="rtl"] .dds-card-has-arrow {
+  padding-right: var(--dds-card-padding);
+  padding-left: calc(var(--dds-card-padding) + 1.25rem);
+}
+.dds-card-arrow {
+  position: absolute;
+  bottom: var(--dds-card-arrow-inset);
+  right: var(--dds-card-arrow-inset);
+  color: var(--dds-card-arrow-color);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+}
+[dir="rtl"] .dds-card-arrow {
+  right: auto;
+  left: var(--dds-card-arrow-inset);
+  transform: scaleX(-1);
+}
+@keyframes dds-arrow-nudge {
+  0%   { transform: translateX(0); }
+  40%  { transform: translateX(5px); }
+  70%  { transform: translateX(-2px); }
+  100% { transform: translateX(0); }
+}
+@keyframes dds-arrow-nudge-rtl {
+  0%   { transform: scaleX(-1) translateX(0); }
+  40%  { transform: scaleX(-1) translateX(5px); }
+  70%  { transform: scaleX(-1) translateX(-2px); }
+  100% { transform: scaleX(-1) translateX(0); }
+}
+.dds-card-clickable:hover .dds-card-arrow {
+  animation: dds-arrow-nudge 0.4s cubic-bezier(0.34, 1.56, 0.64, 1) forwards;
+}
+[dir="rtl"] .dds-card-clickable:hover .dds-card-arrow {
+  animation: dds-arrow-nudge-rtl 0.4s cubic-bezier(0.34, 1.56, 0.64, 1) forwards;
+}
 /* Text color variants */
 .dds-card-text-blue {
   color: var(--dds-card-text-blue);
@@ -1273,6 +1361,7 @@ a.no-text-decoration {
   display: grid;
   grid-template-rows: 0fr;
   transition: grid-template-rows 0.3s ease;
+  overflow: hidden;
 }
 .dds-collapser-content-wrapper--open {
   grid-template-rows: 1fr;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roadlittledawn/docs-design-system-react",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "license": "MIT",
   "description": "React components for documentation design system",
   "repository": {