ai-design-system 0.1.0

package/components/primitives/Avatar/Avatar.stories.tsx

@@ -0,0 +1,321 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Avatar, AvatarFallback, AvatarImage } from "./Avatar";
+
+/**
+ * Avatar component displays a user profile picture with automatic fallback support.
+ *
+ * ## Features
+ * - Automatic image loading with fallback
+ * - Circular design (default) or custom shapes
+ * - Size customization
+ * - Lazy loading support
+ * - Accessible with proper alt text
+ * - WCAG 2.1 Level AA compliant
+ *
+ * ## Usage
+ * ```tsx
+ * <Avatar>
+ *   <AvatarImage src="/user.jpg" alt="User Name" />
+ *   <AvatarFallback>UN</AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * ## Accessibility
+ * - Always provide alt text for AvatarImage
+ * - Fallback should contain initials or descriptive text
+ * - Support for screen readers
+ */
+const meta: Meta<typeof Avatar> = {
+  title: "Primitives/Avatar",
+  component: Avatar,
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component:
+          "An image element with a fallback for representing a user or entity.",
+      },
+    },
+  },
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Avatar>;
+
+/**
+ * Default avatar with image
+ */
+export const Default: Story = {
+  render: () => (
+    <Avatar>
+      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+      <AvatarFallback>CN</AvatarFallback>
+    </Avatar>
+  ),
+};
+
+/**
+ * Avatar with fallback (when image fails to load)
+ */
+export const WithFallback: Story = {
+  render: () => (
+    <Avatar>
+      <AvatarImage src="/invalid-image-url.jpg" alt="User" />
+      <AvatarFallback>JD</AvatarFallback>
+    </Avatar>
+  ),
+};
+
+/**
+ * Different avatar sizes
+ */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Avatar className="size-6">
+        <AvatarImage src="https://github.com/shadcn.png" alt="Small" />
+        <AvatarFallback className="text-xs">XS</AvatarFallback>
+      </Avatar>
+
+      <Avatar className="size-8">
+        <AvatarImage src="https://github.com/shadcn.png" alt="Default" />
+        <AvatarFallback className="text-sm">SM</AvatarFallback>
+      </Avatar>
+
+      <Avatar className="size-12">
+        <AvatarImage src="https://github.com/shadcn.png" alt="Medium" />
+        <AvatarFallback>MD</AvatarFallback>
+      </Avatar>
+
+      <Avatar className="size-16">
+        <AvatarImage src="https://github.com/shadcn.png" alt="Large" />
+        <AvatarFallback className="text-lg">LG</AvatarFallback>
+      </Avatar>
+
+      <Avatar className="size-24">
+        <AvatarImage src="https://github.com/shadcn.png" alt="Extra Large" />
+        <AvatarFallback className="text-2xl">XL</AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+/**
+ * Avatar with initials fallback
+ */
+export const WithInitials: Story = {
+  render: () => (
+    <div className="flex gap-4">
+      <Avatar>
+        <AvatarFallback>AB</AvatarFallback>
+      </Avatar>
+
+      <Avatar>
+        <AvatarFallback>CD</AvatarFallback>
+      </Avatar>
+
+      <Avatar>
+        <AvatarFallback>EF</AvatarFallback>
+      </Avatar>
+
+      <Avatar>
+        <AvatarFallback>GH</AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+/**
+ * Avatar with colored backgrounds
+ */
+export const ColoredFallbacks: Story = {
+  render: () => (
+    <div className="flex gap-4">
+      <Avatar>
+        <AvatarFallback className="bg-red-500 text-white">AB</AvatarFallback>
+      </Avatar>
+
+      <Avatar>
+        <AvatarFallback className="bg-blue-500 text-white">CD</AvatarFallback>
+      </Avatar>
+
+      <Avatar>
+        <AvatarFallback className="bg-green-500 text-white">EF</AvatarFallback>
+      </Avatar>
+
+      <Avatar>
+        <AvatarFallback className="bg-purple-500 text-white">GH</AvatarFallback>
+      </Avatar>
+
+      <Avatar>
+        <AvatarFallback className="bg-orange-500 text-white">IJ</AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+/**
+ * Avatar with icon fallback
+ */
+export const WithIcon: Story = {
+  render: () => (
+    <div className="flex gap-4">
+      <Avatar>
+        <AvatarImage src="/invalid.jpg" alt="User" />
+        <AvatarFallback>
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="20"
+            height="20"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" />
+            <circle cx="12" cy="7" r="4" />
+          </svg>
+        </AvatarFallback>
+      </Avatar>
+
+      <Avatar className="size-12">
+        <AvatarImage src="/invalid.jpg" alt="User" />
+        <AvatarFallback>
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" />
+            <circle cx="12" cy="7" r="4" />
+          </svg>
+        </AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+/**
+ * Avatar group (stacked avatars)
+ */
+export const AvatarGroup: Story = {
+  render: () => (
+    <div className="flex -space-x-4">
+      <Avatar className="border-2 border-background">
+        <AvatarImage src="https://github.com/shadcn.png" alt="User 1" />
+        <AvatarFallback>U1</AvatarFallback>
+      </Avatar>
+      <Avatar className="border-2 border-background">
+        <AvatarImage src="https://github.com/vercel.png" alt="User 2" />
+        <AvatarFallback>U2</AvatarFallback>
+      </Avatar>
+      <Avatar className="border-2 border-background">
+        <AvatarFallback>U3</AvatarFallback>
+      </Avatar>
+      <Avatar className="border-2 border-background">
+        <AvatarFallback>U4</AvatarFallback>
+      </Avatar>
+      <Avatar className="border-2 border-background">
+        <AvatarFallback className="text-xs">+5</AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+/**
+ * Avatar with status indicator
+ */
+export const WithStatus: Story = {
+  render: () => (
+    <div className="flex gap-4">
+      <div className="relative">
+        <Avatar>
+          <AvatarImage src="https://github.com/shadcn.png" alt="Online user" />
+          <AvatarFallback>ON</AvatarFallback>
+        </Avatar>
+        <span className="absolute bottom-0 right-0 block size-3 rounded-full bg-green-500 ring-2 ring-background" />
+      </div>
+
+      <div className="relative">
+        <Avatar>
+          <AvatarImage src="https://github.com/vercel.png" alt="Away user" />
+          <AvatarFallback>AW</AvatarFallback>
+        </Avatar>
+        <span className="absolute bottom-0 right-0 block size-3 rounded-full bg-yellow-500 ring-2 ring-background" />
+      </div>
+
+      <div className="relative">
+        <Avatar>
+          <AvatarFallback>OF</AvatarFallback>
+        </Avatar>
+        <span className="absolute bottom-0 right-0 block size-3 rounded-full bg-gray-400 ring-2 ring-background" />
+      </div>
+
+      <div className="relative">
+        <Avatar>
+          <AvatarFallback>DND</AvatarFallback>
+        </Avatar>
+        <span className="absolute bottom-0 right-0 block size-3 rounded-full bg-red-500 ring-2 ring-background" />
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Square avatar (custom shape)
+ */
+export const SquareShape: Story = {
+  render: () => (
+    <div className="flex gap-4">
+      <Avatar className="rounded-md">
+        <AvatarImage src="https://github.com/shadcn.png" alt="Square avatar" />
+        <AvatarFallback>SQ</AvatarFallback>
+      </Avatar>
+
+      <Avatar className="rounded-lg size-12">
+        <AvatarImage src="https://github.com/vercel.png" alt="Rounded square" />
+        <AvatarFallback>RS</AvatarFallback>
+      </Avatar>
+
+      <Avatar className="rounded-none size-12">
+        <AvatarFallback>NS</AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+/**
+ * Dark mode support
+ */
+export const DarkMode: Story = {
+  parameters: {
+    backgrounds: { default: "dark" },
+  },
+  render: () => (
+    <div className="dark flex gap-4">
+      <Avatar>
+        <AvatarImage src="https://github.com/shadcn.png" alt="Dark mode" />
+        <AvatarFallback>DM</AvatarFallback>
+      </Avatar>
+
+      <Avatar>
+        <AvatarFallback>AB</AvatarFallback>
+      </Avatar>
+
+      <Avatar>
+        <AvatarFallback className="bg-primary text-primary-foreground">
+          CD
+        </AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};

package/components/primitives/Avatar/Avatar.tsx

@@ -0,0 +1,63 @@
+"use client";
+
+import * as React from "react";
+import {
+  Avatar as ShadcnAvatar,
+  AvatarImage as ShadcnAvatarImage,
+  AvatarFallback as ShadcnAvatarFallback,
+} from "@/components/ui/avatar";
+
+/**
+ * Avatar Primitive
+ *
+ * An image element with a fallback for representing a user or entity.
+ *
+ * Features:
+ * - Automatic image loading with fallback
+ * - Circular or custom shape support
+ * - Size customization via className
+ * - Lazy loading support
+ * - WCAG 2.1 Level AA compliant
+ */
+
+export type AvatarProps = React.ComponentProps<typeof ShadcnAvatar>;
+export type AvatarImageProps = React.ComponentProps<typeof ShadcnAvatarImage>;
+export type AvatarFallbackProps = React.ComponentProps<typeof ShadcnAvatarFallback>;
+
+/**
+ * Avatar - Root container for the avatar component
+ */
+export const Avatar = React.memo<AvatarProps>(
+  React.forwardRef<React.ElementRef<typeof ShadcnAvatar>, AvatarProps>(
+    (props, ref) => {
+      return <ShadcnAvatar ref={ref} {...props} />;
+    }
+  )
+);
+Avatar.displayName = "Avatar";
+
+/**
+ * AvatarImage - The image element
+ * Falls back to AvatarFallback if image fails to load
+ */
+export const AvatarImage = React.memo<AvatarImageProps>(
+  React.forwardRef<React.ElementRef<typeof ShadcnAvatarImage>, AvatarImageProps>(
+    (props, ref) => {
+      return <ShadcnAvatarImage ref={ref} {...props} />;
+    }
+  )
+);
+AvatarImage.displayName = "AvatarImage";
+
+/**
+ * AvatarFallback - Fallback content when image is unavailable
+ * Typically displays initials or an icon
+ */
+export const AvatarFallback = React.memo<AvatarFallbackProps>(
+  React.forwardRef<React.ElementRef<typeof ShadcnAvatarFallback>, AvatarFallbackProps>(
+    (props, ref) => {
+      return <ShadcnAvatarFallback ref={ref} {...props} />;
+    }
+  )
+);
+AvatarFallback.displayName = "AvatarFallback";

package/components/primitives/Avatar/index.ts

@@ -0,0 +1,8 @@
+export {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  type AvatarProps,
+  type AvatarFallbackProps,
+  type AvatarImageProps,
+} from "./Avatar";

package/components/primitives/Badge/Badge.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { Badge } from "./Badge"
+
+const meta = {
+  title: "Primitives/Badge",
+  component: Badge,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof Badge>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  render: () => <Badge>Default</Badge>,
+}
+
+export const Secondary: Story = {
+  render: () => <Badge variant="secondary">Secondary</Badge>,
+}
+
+export const Destructive: Story = {
+  render: () => <Badge variant="destructive">Destructive</Badge>,
+}
+
+export const Outline: Story = {
+  render: () => <Badge variant="outline">Outline</Badge>,
+}
+
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex gap-2 flex-wrap">
+      <Badge>Default</Badge>
+      <Badge variant="secondary">Secondary</Badge>
+      <Badge variant="destructive">Destructive</Badge>
+      <Badge variant="outline">Outline</Badge>
+    </div>
+  ),
+}
+
+export const WithIcons: Story = {
+  render: () => (
+    <div className="flex gap-2 flex-wrap">
+      <Badge>
+        <span className="size-2 rounded-full bg-green-500" />
+        Active
+      </Badge>
+      <Badge variant="secondary">
+        <span className="size-2 rounded-full bg-yellow-500" />
+        Pending
+      </Badge>
+      <Badge variant="destructive">
+        <span className="size-2 rounded-full bg-white" />
+        Inactive
+      </Badge>
+    </div>
+  ),
+}
+
+export const DarkMode: Story = {
+  parameters: {
+    backgrounds: { default: "dark" },
+  },
+  render: () => (
+    <div className="dark flex gap-2">
+      <Badge>Default</Badge>
+      <Badge variant="secondary">Secondary</Badge>
+      <Badge variant="destructive">Destructive</Badge>
+      <Badge variant="outline">Outline</Badge>
+    </div>
+  ),
+}

package/components/primitives/Badge/Badge.tsx

@@ -0,0 +1,49 @@
+import * as React from "react"
+import { Badge as ShadcnBadge, badgeVariants } from "../../ui/badge"
+import type { VariantProps } from "class-variance-authority"
+
+/**
+ * Badge Primitive
+ *
+ * A small status indicator component for labels, counts, and status.
+ * Built with CVA for variant management.
+ *
+ * @see https://ui.shadcn.com/docs/components/badge
+ */
+
+export type BadgeProps = React.ComponentProps<"span"> &
+  VariantProps<typeof badgeVariants> & {
+    asChild?: boolean
+  }
+
+/**
+ * Badge component
+ *
+ * A small status indicator component for labels, counts, and status.
+ * Optimized with React.memo for performance in high-frequency rendering scenarios.
+ *
+ * Features:
+ * - Multiple variants for different contexts (default, secondary, destructive, outline)
+ * - Flexible sizing and composition
+ * - Dark mode support
+ * - Can be rendered as a child element using asChild prop
+ */
+export const Badge = React.memo(
+  React.forwardRef<HTMLSpanElement, BadgeProps>(
+    (props, ref) => {
+      return <ShadcnBadge ref={ref} {...props} />
+    }
+  )
+)
+
+Badge.displayName = "Badge"
+
+/**
+ * Re-export badgeVariants for consumers who need direct access to the variant generator.
+ */
+export { badgeVariants }
+
+/**
+ * Re-export VariantProps for type inference in consuming components
+ */
+export type { VariantProps }

package/components/primitives/Badge/index.ts

@@ -0,0 +1,2 @@
+export { Badge, badgeVariants } from "./Badge"
+export type { BadgeProps, VariantProps } from "./Badge"