@neoptocom/neopto-ui 1.4.4 → 1.5.0

package/dist/index.cjs

@@ -265,28 +265,81 @@ function Card({
   );
 }
 var Input = React3__namespace.forwardRef(
-  ({ className, disabled, variant = "default", ...props }, ref) => {
-    const isInline = variant === "inline";
-    return /* @__PURE__ */ jsxRuntime.jsx(
-      "input",
+  ({
+    className,
+    disabled,
+    variant = "default",
+    label,
+    fieldsetProps,
+    legendProps,
+    error = false,
+    ...props
+  }, ref) => {
+    const isInlineVariant = variant === "inline";
+    const shouldUseInlineStyles = isInlineVariant || Boolean(label);
+    const isError = error && !disabled;
+    const inputClasses = [
+      "w-full bg-transparent outline-none transition-colors",
+      shouldUseInlineStyles ? "h-9" : "h-12 px-4 rounded-full",
+      "font-['Poppins'] text-sm placeholder:text-[var(--muted-fg)]"
+    ];
+    if (!shouldUseInlineStyles) {
+      inputClasses.push("border");
+    }
+    if (disabled) {
+      inputClasses.push("text-[#3F424F]", "cursor-not-allowed");
+      if (!shouldUseInlineStyles) {
+        inputClasses.push("border-[#3F424F]");
+      }
+    } else {
+      inputClasses.push("text-[var(--muted-fg)]", "focus:text-[var(--fg)]");
+      if (!shouldUseInlineStyles) {
+        inputClasses.push(
+          isError ? "border-[var(--destructive)]" : "border-[var(--muted-fg)]",
+          isError ? "hover:border-[var(--destructive)]" : "hover:border-[var(--border)]",
+          isError ? "focus:border-[var(--destructive)]" : "focus:border-[var(--color-brand)]"
+        );
+      }
+    }
+    if (className) {
+      inputClasses.push(className);
+    }
+    const inputClassName = inputClasses.join(" ");
+    const inputElement = /* @__PURE__ */ jsxRuntime.jsx("input", { ref, disabled, className: inputClassName, ...props });
+    if (!label) {
+      return inputElement;
+    }
+    const { className: fieldsetClassNameProp = "", ...restFieldsetProps } = fieldsetProps ?? {};
+    const { className: legendClassNameProp = "", ...restLegendProps } = legendProps ?? {};
+    const fieldsetClassName = [
+      "w-full min-w-0 rounded-full border bg-[var(--surface)] transition-colors h-14",
+      isError ? "border-[var(--destructive)]" : "border-[var(--border)]",
+      isError ? "focus-within:border-[var(--destructive)]" : "focus-within:border-[var(--color-brand)]",
+      disabled ? "opacity-60 cursor-not-allowed" : "",
+      fieldsetClassNameProp
+    ].filter(Boolean).join(" ");
+    const legendColorClass = disabled ? "text-[var(--muted-fg)]" : isError ? "text-[var(--destructive)]" : "text-[var(--muted-fg)]";
+    const legendClassNameCombined = [
+      "ml-4 px-1 text-sm leading-none relative font-normal select-none",
+      legendColorClass,
+      legendClassNameProp
+    ].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsxRuntime.jsxs(
+      "fieldset",
       {
-        ref,
-        disabled,
-        className: [
-          "w-full bg-transparent outline-none transition-colors",
-          isInline ? "" : "h-12 px-4 rounded-full",
-          "font-['Poppins'] text-sm placeholder:text-[var(--muted-fg)]",
-          !isInline && "border",
-          disabled ? "text-[#3F424F] cursor-not-allowed" + (isInline ? "" : " border-[#3F424F]") : [
-            "text-[var(--muted-fg)]",
-            isInline ? "" : "border-[var(--muted-fg)]",
-            isInline ? "" : "hover:border-[var(--border)]",
-            "focus:text-[var(--fg)]",
-            isInline ? "" : "focus:border-[var(--color-brand)]"
-          ].join(" "),
-          className
-        ].join(" "),
-        ...props
+        ...restFieldsetProps,
+        className: fieldsetClassName,
+        children: [
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "legend",
+            {
+              ...restLegendProps,
+              className: legendClassNameCombined,
+              children: label
+            }
+          ),
+          /* @__PURE__ */ jsxRuntime.jsx("div", { className: "relative flex pl-5 pr-3 pb-1 h-full", children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex w-full", children: inputElement }) })
+        ]
       }
     );
   }

package/dist/index.d.cts

@@ -59,13 +59,29 @@ type CardProps = React.HTMLAttributes<HTMLDivElement> & {
 };
 declare function Card({ children, className, style, showDecorations, variant, elevated, lightImage, darkImage, ...props }: CardProps): react_jsx_runtime.JSX.Element;
 
-type InputProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> & {
+type InputProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "size"> & {
     /** Input visual variant */
     variant?: "default" | "inline";
+    /** Optional floating label (renders a fieldset wrapper when provided) */
+    label?: string;
+    /** Additional props for the surrounding fieldset when label is set */
+    fieldsetProps?: React.FieldsetHTMLAttributes<HTMLFieldSetElement>;
+    /** Additional props for the legend when label is set */
+    legendProps?: React.HTMLAttributes<HTMLLegendElement>;
+    /** Flag to visually mark the input as errored */
+    error?: boolean;
 };
 declare const Input: React.ForwardRefExoticComponent<Omit<React.InputHTMLAttributes<HTMLInputElement>, "size"> & {
     /** Input visual variant */
     variant?: "default" | "inline";
+    /** Optional floating label (renders a fieldset wrapper when provided) */
+    label?: string;
+    /** Additional props for the surrounding fieldset when label is set */
+    fieldsetProps?: React.FieldsetHTMLAttributes<HTMLFieldSetElement>;
+    /** Additional props for the legend when label is set */
+    legendProps?: React.HTMLAttributes<HTMLLegendElement>;
+    /** Flag to visually mark the input as errored */
+    error?: boolean;
 } & React.RefAttributes<HTMLInputElement>>;
 
 type TextareaProps = Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'size'> & {

package/dist/index.d.ts

@@ -59,13 +59,29 @@ type CardProps = React.HTMLAttributes<HTMLDivElement> & {
 };
 declare function Card({ children, className, style, showDecorations, variant, elevated, lightImage, darkImage, ...props }: CardProps): react_jsx_runtime.JSX.Element;
 
-type InputProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> & {
+type InputProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "size"> & {
     /** Input visual variant */
     variant?: "default" | "inline";
+    /** Optional floating label (renders a fieldset wrapper when provided) */
+    label?: string;
+    /** Additional props for the surrounding fieldset when label is set */
+    fieldsetProps?: React.FieldsetHTMLAttributes<HTMLFieldSetElement>;
+    /** Additional props for the legend when label is set */
+    legendProps?: React.HTMLAttributes<HTMLLegendElement>;
+    /** Flag to visually mark the input as errored */
+    error?: boolean;
 };
 declare const Input: React.ForwardRefExoticComponent<Omit<React.InputHTMLAttributes<HTMLInputElement>, "size"> & {
     /** Input visual variant */
     variant?: "default" | "inline";
+    /** Optional floating label (renders a fieldset wrapper when provided) */
+    label?: string;
+    /** Additional props for the surrounding fieldset when label is set */
+    fieldsetProps?: React.FieldsetHTMLAttributes<HTMLFieldSetElement>;
+    /** Additional props for the legend when label is set */
+    legendProps?: React.HTMLAttributes<HTMLLegendElement>;
+    /** Flag to visually mark the input as errored */
+    error?: boolean;
 } & React.RefAttributes<HTMLInputElement>>;
 
 type TextareaProps = Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'size'> & {

package/dist/index.js

@@ -244,28 +244,81 @@ function Card({
   );
 }
 var Input = React3.forwardRef(
-  ({ className, disabled, variant = "default", ...props }, ref) => {
-    const isInline = variant === "inline";
-    return /* @__PURE__ */ jsx(
-      "input",
+  ({
+    className,
+    disabled,
+    variant = "default",
+    label,
+    fieldsetProps,
+    legendProps,
+    error = false,
+    ...props
+  }, ref) => {
+    const isInlineVariant = variant === "inline";
+    const shouldUseInlineStyles = isInlineVariant || Boolean(label);
+    const isError = error && !disabled;
+    const inputClasses = [
+      "w-full bg-transparent outline-none transition-colors",
+      shouldUseInlineStyles ? "h-9" : "h-12 px-4 rounded-full",
+      "font-['Poppins'] text-sm placeholder:text-[var(--muted-fg)]"
+    ];
+    if (!shouldUseInlineStyles) {
+      inputClasses.push("border");
+    }
+    if (disabled) {
+      inputClasses.push("text-[#3F424F]", "cursor-not-allowed");
+      if (!shouldUseInlineStyles) {
+        inputClasses.push("border-[#3F424F]");
+      }
+    } else {
+      inputClasses.push("text-[var(--muted-fg)]", "focus:text-[var(--fg)]");
+      if (!shouldUseInlineStyles) {
+        inputClasses.push(
+          isError ? "border-[var(--destructive)]" : "border-[var(--muted-fg)]",
+          isError ? "hover:border-[var(--destructive)]" : "hover:border-[var(--border)]",
+          isError ? "focus:border-[var(--destructive)]" : "focus:border-[var(--color-brand)]"
+        );
+      }
+    }
+    if (className) {
+      inputClasses.push(className);
+    }
+    const inputClassName = inputClasses.join(" ");
+    const inputElement = /* @__PURE__ */ jsx("input", { ref, disabled, className: inputClassName, ...props });
+    if (!label) {
+      return inputElement;
+    }
+    const { className: fieldsetClassNameProp = "", ...restFieldsetProps } = fieldsetProps ?? {};
+    const { className: legendClassNameProp = "", ...restLegendProps } = legendProps ?? {};
+    const fieldsetClassName = [
+      "w-full min-w-0 rounded-full border bg-[var(--surface)] transition-colors h-14",
+      isError ? "border-[var(--destructive)]" : "border-[var(--border)]",
+      isError ? "focus-within:border-[var(--destructive)]" : "focus-within:border-[var(--color-brand)]",
+      disabled ? "opacity-60 cursor-not-allowed" : "",
+      fieldsetClassNameProp
+    ].filter(Boolean).join(" ");
+    const legendColorClass = disabled ? "text-[var(--muted-fg)]" : isError ? "text-[var(--destructive)]" : "text-[var(--muted-fg)]";
+    const legendClassNameCombined = [
+      "ml-4 px-1 text-sm leading-none relative font-normal select-none",
+      legendColorClass,
+      legendClassNameProp
+    ].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsxs(
+      "fieldset",
       {
-        ref,
-        disabled,
-        className: [
-          "w-full bg-transparent outline-none transition-colors",
-          isInline ? "" : "h-12 px-4 rounded-full",
-          "font-['Poppins'] text-sm placeholder:text-[var(--muted-fg)]",
-          !isInline && "border",
-          disabled ? "text-[#3F424F] cursor-not-allowed" + (isInline ? "" : " border-[#3F424F]") : [
-            "text-[var(--muted-fg)]",
-            isInline ? "" : "border-[var(--muted-fg)]",
-            isInline ? "" : "hover:border-[var(--border)]",
-            "focus:text-[var(--fg)]",
-            isInline ? "" : "focus:border-[var(--color-brand)]"
-          ].join(" "),
-          className
-        ].join(" "),
-        ...props
+        ...restFieldsetProps,
+        className: fieldsetClassName,
+        children: [
+          /* @__PURE__ */ jsx(
+            "legend",
+            {
+              ...restLegendProps,
+              className: legendClassNameCombined,
+              children: label
+            }
+          ),
+          /* @__PURE__ */ jsx("div", { className: "relative flex pl-5 pr-3 pb-1 h-full", children: /* @__PURE__ */ jsx("div", { className: "flex w-full", children: inputElement }) })
+        ]
       }
     );
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neoptocom/neopto-ui",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "private": false,
   "description": "A modern React component library built with Tailwind CSS v4 and TypeScript. Features dark mode, design tokens, and comprehensive Storybook documentation. Requires Tailwind v4+.",
   "keywords": [
@@ -49,6 +49,7 @@
     "typecheck": "tsc --noEmit",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
+    "storybook:docs": "storybook build --docs --output-dir storybook-static && cp storybook-static/index.json storybook-static/docs.json",
     "prepublishOnly": "npm run build && npm run typecheck",
     "changeset": "changeset",
     "version-packages": "changeset version",
@@ -58,9 +59,9 @@
     "react": ">=18",
     "react-dom": ">=18"
   },
-  "dependencies": {},
   "devDependencies": {
     "@changesets/cli": "^2.27.8",
+    "@joshwooding/vite-plugin-react-docgen-typescript": "^0.6.2",
     "@storybook/addon-actions": "^8.1.0",
     "@storybook/addon-essentials": "^8.1.0",
     "@storybook/addon-interactions": "^8.1.0",

package/src/components/Breadcrumb.docs.mdx

@@ -0,0 +1,60 @@
+import { Meta, Canvas, Story, ArgsTable } from "@storybook/blocks";
+import { Breadcrumb } from "./Breadcrumb";
+import * as BreadcrumbStories from "./Breadcrumb.stories";
+
+<Meta of={BreadcrumbStories} />
+
+# Breadcrumb
+
+The `Breadcrumb` component displays the current location within a hierarchy and optional navigation
+links for parent levels. It supports icons, external links, and click handlers for in-app routing.
+
+## When to use
+
+- Help users understand where they are in a nested content structure.
+- Offer a quick path back to previous sections without duplicating navigation in headers or sidebars.
+- Pair with routed or client-side navigation; items accept either `href` or `onClick`.
+
+## Basic usage
+
+```tsx
+import { Breadcrumb } from "@neoptocom/neopto-ui";
+
+const items = [
+  { label: "Home", href: "/" },
+  { label: "Docs", href: "/docs" },
+  { label: "Components" }
+];
+
+<Breadcrumb items={items} showHomeIcon />;
+```
+
+<Canvas>
+  <Story of={BreadcrumbStories.Playground} />
+</Canvas>
+
+<ArgsTable of={BreadcrumbStories.Playground} />
+
+## Design guidance
+
+- Keep labels short; truncate or abbreviate long section names where possible.
+- Provide icons sparingly to reinforce key contexts (e.g., folders vs. people).
+- Use `showHomeIcon` to reinforce a “home” entry without duplicating the label.
+- Avoid mixing `href` and `onClick` handlers on the same item.
+
+## Composing with state
+
+Combine breadcrumb click handlers with your router or state machine to switch views without a full
+page load. The interactive example demonstrates an in-app documents flow.
+
+<Canvas>
+  <Story of={BreadcrumbStories.InteractiveNavigation} />
+</Canvas>
+
+## Accessibility
+
+- Breadcrumbs are wrapped in a `<nav aria-label="Breadcrumb">` for screen readers.
+- The final item receives `aria-current="page"` automatically.
+- Clickable items expose keyboard handlers, so always keep labels descriptive.
+
+

package/src/components/Breadcrumb.stories.tsx

@@ -0,0 +1,78 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import { Breadcrumb, type BreadcrumbItem } from "./Breadcrumb";
+
+const meta: Meta<typeof Breadcrumb> = {
+  title: "Components/Breadcrumb",
+  component: Breadcrumb,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered"
+  },
+  args: {
+    items: [
+      { label: "Home", href: "/" },
+      { label: "Library", href: "/library" },
+      { label: "Data" }
+    ] satisfies BreadcrumbItem[]
+  }
+};
+
+export default meta;
+type Story = StoryObj<typeof Breadcrumb>;
+
+export const Playground: Story = {};
+
+export const WithIcons: Story = {
+  args: {
+    items: [
+      { label: "Dashboard", href: "/", icon: "dashboard" },
+      { label: "Projects", href: "/projects", icon: "folder" },
+      { label: "Neptune Launch", icon: "rocket_launch" }
+    ]
+  }
+};
+
+export const WithHomeIcon: Story = {
+  args: {
+    showHomeIcon: true
+  }
+};
+
+export const InteractiveNavigation: Story = {
+  render: (args) => {
+    const sections: BreadcrumbItem[] = [
+      { label: "Getting Started", href: "/docs/getting-started" },
+      { label: "Guides", href: "/docs/guides" },
+      { label: "Auth", icon: "lock" }
+    ];
+
+    const [activeSection, setActiveSection] = useState(sections[sections.length - 1]);
+
+    return (
+      <div className="flex flex-col gap-6 w-full max-w-3xl">
+        <Breadcrumb
+          {...args}
+          items={[
+            { label: "Docs", href: "/docs", icon: "menu_book" },
+            ...sections.map((section, index) => ({
+              ...section,
+              onClick: () => setActiveSection(section),
+              href: index === sections.length - 1 ? undefined : section.href
+            }))
+          ]}
+        />
+
+        <section className="rounded-lg border border-[var(--border)] bg-[var(--surface)] p-6 space-y-2">
+          <h2 className="text-xl font-semibold">{activeSection.label}</h2>
+          <p className="text-sm text-[var(--muted-fg)]">
+            Showcase how breadcrumbs can drive in-app navigation without reloading the page by
+            combining click handlers with your own state management.
+          </p>
+        </section>
+      </div>
+    );
+  }
+};
+
+

package/src/components/Button.docs.mdx

@@ -0,0 +1,56 @@
+import { Meta, Canvas, Story, ArgsTable } from "@storybook/blocks";
+import { Button } from "./Button";
+import * as ButtonStories from "./Button.stories";
+
+<Meta of={ButtonStories} />
+
+# Button
+
+Buttons trigger primary user actions. They support three visual variants, three sizes, optional full
+width layout, and icon affordances.
+
+## Usage
+
+```tsx
+import { Button } from "@neoptocom/neopto-ui";
+
+<Button variant="primary" size="md">
+  Save changes
+</Button>;
+```
+
+<Canvas>
+  <Story of={ButtonStories.Playground} />
+</Canvas>
+
+<ArgsTable of={ButtonStories.Playground} />
+
+## Variants
+
+Use variants to communicate hierarchy:
+
+- `primary`: main call to action.
+- `secondary`: supporting actions with visual emphasis.
+- `ghost`: low emphasis actions within already prominent surfaces.
+
+<Canvas>
+  <Story of={ButtonStories.Variants} />
+</Canvas>
+
+## Layout
+
+- Aim for one primary button per view; demote additional actions to secondary/ghost.
+- Combine icons with concise labels for quicker scanning.
+- Apply `fullWidth` for responsive mobile layouts or wizard footers.
+
+<Canvas>
+  <Story of={ButtonStories.FullWidthCallToAction} />
+</Canvas>
+
+## Accessibility
+
+- Buttons use semantic `<button>` elements with focus styles.
+- Provide descriptive text even when using icons to ensure screen readers announce intent.
+- Disable buttons sparingly—pair with helper text when an action is unavailable.
+
+

package/src/{stories → components}/Button.stories.tsx

@@ -1,24 +1,25 @@
 import type { Meta, StoryObj } from "@storybook/react";
-import { Button } from "../components/Button";
-import Icon from "../components/Icon";
-import Typo from "../components/Typo";
+import Icon from "./Icon";
+import Typo from "./Typo";
+import { Button } from "./Button";
 
 const meta: Meta<typeof Button> = {
   title: "Components/Button",
   component: Button,
+  tags: ["autodocs"],
   args: {
-    children: "Button",
+    children: "Primary action",
     variant: "primary",
     size: "md",
     disabled: false
   },
   argTypes: {
     variant: {
-      control: "radio",
+      control: "inline-radio",
       options: ["primary", "secondary", "ghost"]
     },
     size: {
-      control: "radio", 
+      control: "inline-radio",
       options: ["sm", "md", "lg"]
     },
     fullWidth: {
@@ -39,13 +40,19 @@ export const Variants: Story = {
   render: () => (
     <div className="flex flex-wrap items-center gap-4">
       <Button variant="primary">
-        <Typo variant="title-sm" bold="semibold">Primary</Typo>
+        <Typo variant="title-sm" bold="semibold">
+          Primary
+        </Typo>
       </Button>
       <Button variant="secondary">
-        <Typo variant="title-sm" bold="semibold">Secondary</Typo>
+        <Typo variant="title-sm" bold="semibold">
+          Secondary
+        </Typo>
       </Button>
       <Button variant="ghost">
-        <Typo variant="title-sm" bold="semibold">Ghost</Typo>
+        <Typo variant="title-sm" bold="semibold">
+          Ghost
+        </Typo>
       </Button>
     </div>
   )
@@ -55,29 +62,19 @@ export const Sizes: Story = {
   render: () => (
     <div className="flex flex-wrap items-center gap-4">
       <Button size="sm">
-        <Typo variant="title-sm" bold="semibold">Small</Typo>
+        <Typo variant="title-sm" bold="semibold">
+          Small
+        </Typo>
       </Button>
       <Button size="md">
-        <Typo variant="title-sm" bold="semibold">Medium</Typo>
+        <Typo variant="title-sm" bold="semibold">
+          Medium
+        </Typo>
       </Button>
       <Button size="lg">
-        <Typo variant="title-sm" bold="semibold">Large</Typo>
-      </Button>
-    </div>
-  )
-};
-
-export const States: Story = {
-  render: () => (
-    <div className="flex flex-wrap items-center gap-4">
-      <Button>
-        <Typo variant="title-sm" bold="semibold">Default</Typo>
-      </Button>
-      <Button disabled>
-        <Typo variant="title-sm" bold="semibold">Disabled</Typo>
-      </Button>
-      <Button fullWidth>
-        <Typo variant="title-sm" bold="semibold">Full Width</Typo>
+        <Typo variant="title-sm" bold="semibold">
+          Large
+        </Typo>
       </Button>
     </div>
   )
@@ -88,16 +85,26 @@ export const WithIcons: Story = {
     <div className="flex flex-wrap items-center gap-4">
       <Button>
         <Icon name="add" />
-        <Typo variant="title-sm" bold="semibold">Add Item</Typo>
+        <span>Add Item</span>
       </Button>
       <Button variant="secondary">
-        <Icon name="delete" />
-        <Typo variant="title-sm" bold="semibold">Delete</Typo>
+        <Icon name="download" />
+        <span>Download</span>
       </Button>
       <Button variant="ghost">
         <Icon name="settings" />
-        <Typo variant="title-sm" bold="semibold">Settings</Typo>
+        <span>Settings</span>
       </Button>
     </div>
   )
 };
+
+export const FullWidthCallToAction: Story = {
+  args: {
+    fullWidth: true,
+    size: "lg",
+    children: "Start free trial"
+  }
+};
+
+

package/src/components/Card.docs.mdx

@@ -0,0 +1,56 @@
+import { Meta, Canvas, Story, ArgsTable } from "@storybook/blocks";
+import { Card } from "./Card";
+import * as CardStories from "./Card.stories";
+
+<Meta of={CardStories} />
+
+# Card
+
+Cards provide glassmorphic containers for grouping content. They offer decorative borders, elevated
+shadows, and an app-background variant that mirrors hero surfaces.
+
+## Usage
+
+```tsx
+import { Card } from "@neoptocom/neopto-ui";
+
+<Card>
+  <h3>Weekly summary</h3>
+  <p>Use cards to separate content into digestible surfaces.</p>
+</Card>;
+```
+
+<Canvas>
+  <Story of={CardStories.Playground} />
+</Canvas>
+
+<ArgsTable of={CardStories.Playground} />
+
+## Variants
+
+- `showDecorations` adds gradient strokes suited for marketing hero cards.
+- `variant="app-background"` injects the NeoPTO hero artwork and auto-switches with theme.
+- `elevated` applies a high-emphasis drop shadow—combine with default or app backgrounds.
+
+<Canvas>
+  <Story of={CardStories.AppBackground} />
+</Canvas>
+
+## Layout tips
+
+- Allow cards to breathe: default padding is `p-6`, override via the `className` prop for custom
+  spacing.
+- Stack cards in responsive grids to create dashboards or settings panels.
+- Avoid nesting too many cards; use muted surfaces inside when grouping secondary information.
+
+<Canvas>
+  <Story of={CardStories.DashboardLayout} />
+</Canvas>
+
+## Accessibility
+
+Cards render as semantic `<div>` elements. Provide meaningful headings and maintain contrast ratios
+when overlaying text on app backgrounds. For interactive cards, wrap focusable elements instead of
+attaching click handlers to the card root.
+
+