feat(avatar): Introduce Avatar component with image and fallback support

src/components/atoms/Avatar/Avatar.stories.tsx

@@ -0,0 +1,61 @@
+import type {Meta, StoryObj} from "@storybook/react-vite";
+import {Avatar} from "./Avatar";
+
+const meta = {
+    title: "components/atoms/Avatar",
+    component: Avatar,
+} satisfies Meta<typeof Avatar>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Default avatar with initials fallback
+ */
+export const Default: Story = {
+    args: {
+        fallback: "AM",
+        alt: "Arnab Mandal",
+        size: "md",
+    },
+};
+
+/**
+ * Avatar with real image
+ */
+export const WithImage: Story = {
+    args: {
+        src: "https://i.pravatar.cc/150?img=5",
+        fallback: "AM",
+        alt: "User profile",
+        size: "md",
+    },
+};
+
+/**
+ * Broken image → fallback test
+ */
+export const BrokenImage: Story = {
+    args: {
+        src: "https://example.com/invalid-image.jpg",
+        fallback: "NA",
+        alt: "Broken avatar",
+        size: "md",
+    },
+};
+
+/**
+ * All sizes preview
+ */
+export const Sizes: Story = {
+    render: () => (
+        <div style={{display: "flex", gap: 16, alignItems: "center"}}>
+            <Avatar fallback="XS" size="xs"/>
+            <Avatar fallback="SM" size="sm"/>
+            <Avatar fallback="MD" size="md"/>
+            <Avatar fallback="LG" size="lg"/>
+            <Avatar fallback="XL" size="xl"/>
+        </div>
+    ),
+};

src/components/atoms/Avatar/Avatar.tsx

@@ -0,0 +1,96 @@
+import {useEffect, useState} from "react";
+import type {AvatarProps, AvatarSize} from "./AvatarProps";
+
+const sizeMap: Record<AvatarSize, number> = {
+    xs: 24,
+    sm: 32,
+    md: 40,
+    lg: 56,
+    xl: 72,
+};
+
+/**
+ * Renders an Avatar component.
+ *
+ * Displays a user profile image when `src` is provided.
+ * Falls back to initials or a placeholder when the image is missing or fails to load.
+ *
+ * @param {Readonly<AvatarProps>} props - Avatar properties
+ * @returns {React.ReactNode} Rendered avatar
+ *
+ * @example
+ * <Avatar src="https://example.com/avatar.jpg" alt="User Avatar" />
+ *
+ * @example
+ * <Avatar size="lg" fallback="JD" />
+ *
+ * @example
+ * <Avatar src="https://example.com/avatar.jpg" className="my-avatar" />
+ *
+ * @example
+ * <Avatar size="sm" />
+ */
+export function Avatar(props: Readonly<AvatarProps>) {
+    const {
+        src,
+        alt = "Avatar",
+        size = "md",
+        fallback,
+        className,
+    } = props;
+
+    const [hasError, setHasError] = useState(false);
+
+    // Reset error state when image source changes
+    useEffect(() => {
+        setHasError(false);
+    }, [src]);
+
+    const pixelSize = sizeMap[size];
+    const showImage = Boolean(src) && !hasError;
+
+    // IMAGE RENDER
+    if (showImage) {
+        return (
+            <img
+                src={src}
+                alt={alt}
+                width={pixelSize}
+                height={pixelSize}
+                className={className}
+                onError={(e) => {
+                    // prevent infinite error loop
+                    e.currentTarget.onerror = null;
+                    setHasError(true);
+                }}
+                style={{
+                    borderRadius: "50%",
+                    objectFit: "cover",
+                }}
+            />
+        );
+    }
+
+    // FALLBACK RENDER
+    return (
+        <div
+            aria-label={alt}
+            className={className}
+            style={{
+                width: pixelSize,
+                height: pixelSize,
+                borderRadius: "50%",
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                backgroundColor: "#e5e7eb",
+                color: "#374151",
+                fontWeight: 600,
+                fontSize: Math.floor(pixelSize / 2.5),
+                userSelect: "none",
+            }}
+        >
+            {fallback?.slice(0, 2).toUpperCase() ?? "?"}
+        </div>
+    );
+}

src/components/atoms/Avatar/AvatarProps.ts

@@ -0,0 +1,9 @@
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+
+export interface AvatarProps {
+    src?: string;
+    alt?: string;
+    size?: AvatarSize;
+    fallback?: string; // initials OR single char OR icon text
+    className?: string;
+}