From 23e949eedd1d22751148020c94b3a0a77ab6d2c9 Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 21 Mar 2026 19:26:54 +0900
Subject: [PATCH 01/15] =?UTF-8?q?[Feat]=20=ED=8F=BC=20=EB=B0=8F=20?=
 =?UTF-8?q?=ED=8C=8C=EC=9D=BC=20=EC=97=85=EB=A1=9C=EB=8D=94=EC=9A=A9=20?=
 =?UTF-8?q?=EC=95=84=EC=9D=B4=EC=BD=98=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/icons/index.tsx | 62 +++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/src/shared/ui/icons/index.tsx b/src/shared/ui/icons/index.tsx
index 8753a49..536a9d4 100644
--- a/src/shared/ui/icons/index.tsx
+++ b/src/shared/ui/icons/index.tsx
@@ -191,6 +191,68 @@ export const EyeOffIcon: React.FC<IconProps> = ({ size = 20, ...props }) => (
   </svg>
 );
 
+// File Text 아이콘
+export const FileTextIcon: React.FC<IconProps> = ({ size = 20, ...props }) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path d="M14.5 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7.5L14.5 2z" />
+    <polyline points="14 2 14 8 20 8" />
+    <line x1="16" x2="8" y1="13" y2="13" />
+    <line x1="16" x2="8" y1="17" y2="17" />
+    <line x1="10" x2="8" y1="9" y2="9" />
+  </svg>
+);
+
+// Upload 아이콘
+export const UploadIcon: React.FC<IconProps> = ({ size = 20, ...props }) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+    <polyline points="17 8 12 3 7 8" />
+    <line x1="12" x2="12" y1="3" y2="15" />
+  </svg>
+);
+
+// Image 아이콘
+export const ImageIcon: React.FC<IconProps> = ({ size = 20, ...props }) => (
+  <svg
+    width={size}
+    height={size}
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <rect width="18" height="18" x="3" y="3" rx="2" ry="2" />
+    <circle cx="9" cy="9" r="2" />
+    <path d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21" />
+  </svg>
+);
+
 // Chevron Left 아이콘
 export const ChevronLeftIcon: React.FC<IconProps> = ({ size = 20, ...props }) => (
   <svg

From 8f19e8143f01d6d5da8a08089bd4d71d3e3a91ac Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 21 Mar 2026 19:27:03 +0900
Subject: [PATCH 02/15] =?UTF-8?q?[Feat]=20=EA=B3=B5=ED=86=B5=20Form=20?=
 =?UTF-8?q?=EA=B8=B0=EC=B4=88=20=EC=BB=B4=ED=8F=AC=EB=84=8C=ED=8A=B8=20?=
 =?UTF-8?q?=EC=84=B8=ED=8A=B8=20=EA=B5=AC=ED=98=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/form/form.stories.tsx | 162 ++++++++++++++++++++++++++++
 src/shared/ui/form/form.tsx         |  75 +++++++++++++
 src/shared/ui/form/index.ts         |   1 +
 3 files changed, 238 insertions(+)
 create mode 100644 src/shared/ui/form/form.stories.tsx
 create mode 100644 src/shared/ui/form/form.tsx
 create mode 100644 src/shared/ui/form/index.ts

diff --git a/src/shared/ui/form/form.stories.tsx b/src/shared/ui/form/form.stories.tsx
new file mode 100644
index 0000000..ec0cf20
--- /dev/null
+++ b/src/shared/ui/form/form.stories.tsx
@@ -0,0 +1,162 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { FormField, FormLabel, FormHelperText, FormErrorMessage } from "./form";
+import { Input, Textarea } from "@/shared/ui/inputBox/inputBox";
+import { Checkbox } from "@/shared/ui/checkbox/checkbox";
+import {
+  ThumbnailUploader,
+  FileListItem,
+  FileUploader,
+} from "@/shared/ui/file-uploader/file-uploader";
+import { Button } from "@/shared/ui/button/button";
+
+const meta = {
+  title: "Shared/UI/Form",
+  component: FormField,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof FormField>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// --- 종합 폼 예시 (포트폴리오 작성) ---
+const PortfolioCreateForm = () => {
+  const [preview, setPreview] = useState<string | undefined>();
+  const [files, setFiles] = useState([
+    { id: "1", name: "기획서_최종.pdf", size: "1.2 MB", type: "application/pdf" },
+  ]);
+
+  return (
+    <div className="w-[640px] flex flex-col gap-10 bg-white p-10 border rounded-2xl shadow-sm my-10">
+      {/* Header */}
+      <div>
+        <h1 className="text-[32px] font-bold text-[var(--color-gray-900,#111)] mb-2">
+          포트폴리오 작성
+        </h1>
+        <p className="text-[16px] text-[var(--color-gray-500,#666)]">
+          당신의 멋진 프로젝트를 세상에 공유해 보세요.
+        </p>
+      </div>
+
+      {/* Basic Info Section */}
+      <section className="flex flex-col gap-6">
+        <h2 className="text-[20px] font-semibold text-[var(--color-gray-800,#333)] border-b pb-2">
+          기본 정보
+        </h2>
+
+        <FormField>
+          <FormLabel required>프로젝트 제목</FormLabel>
+          <Input placeholder="프로젝트 제목을 입력하세요" />
+        </FormField>
+
+        <FormField>
+          <FormLabel required>간단 설명</FormLabel>
+          <Textarea placeholder="프로젝트를 2-3줄로 요약해 주세요" rows={3} />
+          <FormHelperText>목록 페이지에서 카드 설명으로 사용됩니다.</FormHelperText>
+        </FormField>
+
+        <div className="flex gap-4">
+          <FormField className="flex-1">
+            <FormLabel>기술 스택</FormLabel>
+            <Input placeholder="예: React, TypeScript" />
+          </FormField>
+          <FormField className="flex-1">
+            <FormLabel>역할</FormLabel>
+            <Input placeholder="예: 프론트엔드 개발" />
+          </FormField>
+        </div>
+      </section>
+
+      {/* Media Section */}
+      <section className="flex flex-col gap-6">
+        <h2 className="text-[20px] font-semibold text-[var(--color-gray-800,#333)] border-b pb-2">
+          미디어 및 파일
+        </h2>
+
+        <FormField>
+          <FormLabel required>대표 썸네일</FormLabel>
+          <ThumbnailUploader
+            previewUrl={preview}
+            onUpload={() => setPreview("https://picsum.photos/800/400")}
+            onRemove={() => setPreview(undefined)}
+          />
+          <FormHelperText>권장 해상도: 1200 x 630 (1.91:1)</FormHelperText>
+        </FormField>
+
+        <FormField>
+          <FormLabel>첨부 파일</FormLabel>
+          <div className="flex flex-col gap-3 mb-4">
+            {files.map((file) => (
+              <FileListItem
+                key={file.id}
+                file={file}
+                onRemove={(id) => setFiles(files.filter((f) => f.id !== id))}
+              />
+            ))}
+          </div>
+          <FileUploader onFileSelect={() => {}} />
+        </FormField>
+      </section>
+
+      {/* Policy Section */}
+      <section className="bg-[var(--color-gray-50)] p-6 rounded-xl flex flex-col gap-4">
+        <Checkbox label="위 프로젝트 내용이 사실임을 확인하며, 아주대학교 포트폴리오 운영 정책에 동의합니다." />
+        <Checkbox
+          label="프로젝트를 전체 공개로 설정합니다. (체크 해제 시 나만 보기)"
+          defaultChecked
+        />
+      </section>
+
+      {/* Footer Buttons */}
+      <div className="flex justify-end gap-3 pt-6 border-t">
+        <Button variant="ghost" size="large" className="px-8">
+          임시 저장
+        </Button>
+        <Button variant="primary" size="large" className="px-10">
+          작성 완료
+        </Button>
+      </div>
+    </div>
+  );
+};
+
+export const FullPortfolioForm: Story = {
+  render: () => <PortfolioCreateForm />,
+  args: {
+    children: null,
+  },
+};
+
+// --- 기존 개별 스토리 ---
+export const Default: Story = {
+  render: () => (
+    <div className="w-[400px]">
+      <FormField>
+        <FormLabel required>프로젝트 제목</FormLabel>
+        <Input placeholder="프로젝트 제목을 입력하세요" />
+        <FormHelperText>다른 사람들이 쉽게 알 수 있는 제목을 정해주세요.</FormHelperText>
+      </FormField>
+    </div>
+  ),
+  args: {
+    children: null,
+  },
+};
+
+export const WithError: Story = {
+  render: () => (
+    <div className="w-[400px]">
+      <FormField>
+        <FormLabel required>설명</FormLabel>
+        <Textarea placeholder="상세 내용을 입력하세요" hasError />
+        <FormErrorMessage>설명은 필수 항목입니다.</FormErrorMessage>
+      </FormField>
+    </div>
+  ),
+  args: {
+    children: null,
+  },
+};
diff --git a/src/shared/ui/form/form.tsx b/src/shared/ui/form/form.tsx
new file mode 100644
index 0000000..bddf220
--- /dev/null
+++ b/src/shared/ui/form/form.tsx
@@ -0,0 +1,75 @@
+import type { ReactNode } from "react";
+
+// --- Types ---
+export type FormFieldProps = {
+  children: ReactNode;
+  className?: string;
+};
+
+export type FormLabelProps = {
+  children: ReactNode;
+  required?: boolean;
+  htmlFor?: string;
+  className?: string;
+};
+
+export type FormHelperTextProps = {
+  children: ReactNode;
+  className?: string;
+};
+
+export type FormErrorMessageProps = {
+  children: ReactNode;
+  className?: string;
+};
+
+// --- Styles ---
+
+// 1. FormField
+const fieldBaseClasses = "flex flex-col gap-2 w-full";
+const getFieldClasses = (className?: string) =>
+  [fieldBaseClasses, className].filter(Boolean).join(" ");
+
+// 2. FormLabel
+const labelBaseClasses =
+  "text-[16px] font-medium text-[var(--color-gray-800,#333)] flex items-center gap-1";
+const getLabelClasses = (className?: string) =>
+  [labelBaseClasses, className].filter(Boolean).join(" ");
+
+// 3. FormHelperText
+const helperBaseClasses = "text-[14px] leading-[1.5] text-[var(--color-gray-600,#666)]";
+const getHelperClasses = (className?: string) =>
+  [helperBaseClasses, className].filter(Boolean).join(" ");
+
+// 4. FormErrorMessage
+const errorBaseClasses =
+  "text-[14px] leading-[1.5] text-[var(--color-error-500,#EF4444)] font-medium";
+const getErrorClasses = (className?: string) =>
+  [errorBaseClasses, className].filter(Boolean).join(" ");
+
+// --- Components ---
+
+export const FormField = ({ children, className }: FormFieldProps) => {
+  return <div className={getFieldClasses(className)}>{children}</div>;
+};
+
+export const FormLabel = ({ children, required, htmlFor, className }: FormLabelProps) => {
+  return (
+    <label htmlFor={htmlFor} className={getLabelClasses(className)}>
+      {children}
+      {required && <span className="text-[var(--color-error-500,#EF4444)] ml-0.5">*</span>}
+    </label>
+  );
+};
+
+export const FormHelperText = ({ children, className }: FormHelperTextProps) => {
+  return <p className={getHelperClasses(className)}>{children}</p>;
+};
+
+export const FormErrorMessage = ({ children, className }: FormErrorMessageProps) => {
+  return (
+    <p role="alert" className={getErrorClasses(className)}>
+      {children}
+    </p>
+  );
+};
diff --git a/src/shared/ui/form/index.ts b/src/shared/ui/form/index.ts
new file mode 100644
index 0000000..c4a75a7
--- /dev/null
+++ b/src/shared/ui/form/index.ts
@@ -0,0 +1 @@
+export * from "./form";

From 7210d85ec28fba51ec8a458aa1037d10cdb27514 Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 21 Mar 2026 19:27:12 +0900
Subject: [PATCH 03/15] =?UTF-8?q?[Feat]=20=EB=94=94=EC=9E=90=EC=9D=B8=20?=
 =?UTF-8?q?=EA=B0=80=EC=9D=B4=EB=93=9C=20=EA=B8=B0=EB=B0=98=20=EA=B3=B5?=
 =?UTF-8?q?=ED=86=B5=20Checkbox=20=EC=BB=B4=ED=8F=AC=EB=84=8C=ED=8A=B8=20?=
 =?UTF-8?q?=EA=B5=AC=ED=98=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/checkbox/checkbox.stories.tsx | 62 ++++++++++++++++++
 src/shared/ui/checkbox/checkbox.tsx         | 71 +++++++++++++++++++++
 src/shared/ui/checkbox/index.ts             |  1 +
 3 files changed, 134 insertions(+)
 create mode 100644 src/shared/ui/checkbox/checkbox.stories.tsx
 create mode 100644 src/shared/ui/checkbox/checkbox.tsx
 create mode 100644 src/shared/ui/checkbox/index.ts

diff --git a/src/shared/ui/checkbox/checkbox.stories.tsx b/src/shared/ui/checkbox/checkbox.stories.tsx
new file mode 100644
index 0000000..75b8b3b
--- /dev/null
+++ b/src/shared/ui/checkbox/checkbox.stories.tsx
@@ -0,0 +1,62 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Checkbox, type CheckboxProps } from "./checkbox";
+
+const meta = {
+  title: "Shared/UI/Checkbox",
+  component: Checkbox,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof Checkbox>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// 인터랙션이 가능한 래퍼 컴포넌트
+const InteractiveCheckbox = (args: CheckboxProps) => {
+  const [checked, setChecked] = useState(args.checked || false);
+  return <Checkbox {...args} checked={checked} onChange={(e) => setChecked(e.target.checked)} />;
+};
+
+export const Default: Story = {
+  render: (args) => <InteractiveCheckbox {...args} />,
+  args: {
+    label: "약관에 동의합니다",
+  },
+};
+
+export const Checked: Story = {
+  render: (args) => <InteractiveCheckbox {...args} />,
+  args: {
+    label: "선택된 상태",
+    checked: true,
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    label: "비활성화 상태",
+    disabled: true,
+  },
+};
+
+export const DisabledChecked: Story = {
+  args: {
+    label: "비활성화 및 선택된 상태",
+    disabled: true,
+    checked: true,
+  },
+};
+
+export const List: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <InteractiveCheckbox label="애플" />
+      <InteractiveCheckbox label="바나나" />
+      <InteractiveCheckbox label="오렌지" />
+    </div>
+  ),
+  args: {},
+};
diff --git a/src/shared/ui/checkbox/checkbox.tsx b/src/shared/ui/checkbox/checkbox.tsx
new file mode 100644
index 0000000..97e911e
--- /dev/null
+++ b/src/shared/ui/checkbox/checkbox.tsx
@@ -0,0 +1,71 @@
+import React from "react";
+import { CheckIcon } from "@/shared/ui/icons";
+
+// --- Types ---
+export type CheckboxProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type"> & {
+  label?: string;
+};
+
+// --- Styles ---
+
+// 1. Container & Input
+const containerBaseClasses = "inline-flex items-center gap-2 cursor-pointer group select-none";
+const inputHiddenClasses = "sr-only"; // Screen reader only
+
+// 2. Checkbox Box
+const boxBaseClasses =
+  "w-5 h-5 flex items-center justify-center rounded border transition-all duration-200 ease-out shrink-0";
+
+const getBoxClasses = (checked?: boolean, disabled?: boolean) => {
+  if (disabled) {
+    return [
+      boxBaseClasses,
+      "bg-[var(--color-gray-100,#F2F2F2)] border-[var(--color-gray-200,#E5E5E5)]",
+    ].join(" ");
+  }
+  if (checked) {
+    return [
+      boxBaseClasses,
+      "bg-[var(--color-primary-800,#004A9C)] border-[var(--color-primary-800,#004A9C)]",
+    ].join(" ");
+  }
+  return [
+    boxBaseClasses,
+    "bg-white border-[var(--color-gray-300,#CCCCCC)] group-hover:border-[var(--color-primary-500,#3385DB)]",
+  ].join(" ");
+};
+
+// 3. Label
+const labelBaseClasses =
+  "text-[14px] leading-[1.43] tracking-[-0.35px] transition-colors duration-200";
+const getLabelClasses = (disabled?: boolean) => {
+  const statusClasses = disabled
+    ? "text-[var(--color-gray-400,#999)]"
+    : "text-[var(--color-gray-800,#333)]";
+  return [labelBaseClasses, statusClasses].join(" ");
+};
+
+// --- Component ---
+
+export const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
+  ({ label, checked, disabled, className = "", ...props }, ref) => {
+    return (
+      <label className={[containerBaseClasses, className].join(" ")}>
+        <input
+          type="checkbox"
+          ref={ref}
+          checked={checked}
+          disabled={disabled}
+          className={inputHiddenClasses}
+          {...props}
+        />
+        <div className={getBoxClasses(checked, disabled)}>
+          <CheckIcon size={14} className={checked ? "text-white" : "text-transparent"} />
+        </div>
+        {label && <span className={getLabelClasses(disabled)}>{label}</span>}
+      </label>
+    );
+  },
+);
+
+Checkbox.displayName = "Checkbox";
diff --git a/src/shared/ui/checkbox/index.ts b/src/shared/ui/checkbox/index.ts
new file mode 100644
index 0000000..057f167
--- /dev/null
+++ b/src/shared/ui/checkbox/index.ts
@@ -0,0 +1 @@
+export * from "./checkbox";

From 1b1f2e9996ba4afc6207b495f478397e449d8840 Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 21 Mar 2026 19:27:20 +0900
Subject: [PATCH 04/15] =?UTF-8?q?[Feat]=20=ED=8F=AC=ED=8A=B8=ED=8F=B4?=
 =?UTF-8?q?=EB=A6=AC=EC=98=A4=EC=9A=A9=20=ED=8C=8C=EC=9D=BC=20=EC=97=85?=
 =?UTF-8?q?=EB=A1=9C=EB=8D=94=20=EB=B0=8F=20=EB=A6=AC=EC=8A=A4=ED=8A=B8=20?=
 =?UTF-8?q?=EC=BB=B4=ED=8F=AC=EB=84=8C=ED=8A=B8=20=EA=B5=AC=ED=98=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../file-uploader/file-uploader.stories.tsx   |  70 +++++++
 src/shared/ui/file-uploader/file-uploader.tsx | 174 ++++++++++++++++++
 src/shared/ui/file-uploader/index.ts          |   1 +
 3 files changed, 245 insertions(+)
 create mode 100644 src/shared/ui/file-uploader/file-uploader.stories.tsx
 create mode 100644 src/shared/ui/file-uploader/file-uploader.tsx
 create mode 100644 src/shared/ui/file-uploader/index.ts

diff --git a/src/shared/ui/file-uploader/file-uploader.stories.tsx b/src/shared/ui/file-uploader/file-uploader.stories.tsx
new file mode 100644
index 0000000..d242a48
--- /dev/null
+++ b/src/shared/ui/file-uploader/file-uploader.stories.tsx
@@ -0,0 +1,70 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { ThumbnailUploader, FileListItem, FileUploader } from "./file-uploader";
+
+const meta = {
+  title: "Shared/UI/FileUploader",
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+} satisfies Meta;
+
+export default meta;
+
+const ThumbnailContainer = () => {
+  const [preview, setPreview] = useState<string | undefined>();
+  return (
+    <div className="w-[400px]">
+      <ThumbnailUploader
+        previewUrl={preview}
+        onUpload={() => setPreview("https://picsum.photos/800/400")}
+        onRemove={() => setPreview(undefined)}
+      />
+    </div>
+  );
+};
+
+export const Thumbnail: StoryObj<typeof ThumbnailUploader> = {
+  render: () => <ThumbnailContainer />,
+};
+
+export const FileList: StoryObj<typeof FileListItem> = {
+  render: () => (
+    <div className="w-[400px] flex flex-col gap-3">
+      <FileListItem
+        file={{ id: "1", name: "project-proposal.pdf", size: "2.4 MB", type: "application/pdf" }}
+        onRemove={(id) => console.log("Remove", id)}
+      />
+      <FileListItem
+        file={{ id: "2", name: "main-screenshot.png", size: "1.1 MB", type: "image/png" }}
+        onRemove={(id) => console.log("Remove", id)}
+      />
+    </div>
+  ),
+};
+
+export const CombinedUploader: StoryObj = {
+  render: () => {
+    return (
+      <div className="w-[500px] flex flex-col gap-6 p-8 bg-white border rounded-xl">
+        <div>
+          <h3 className="text-lg font-bold mb-4">포트폴리오 미디어</h3>
+          <p className="text-sm text-gray-500 mb-4">대표 이미지는 검색 결과에 노출됩니다.</p>
+          <ThumbnailUploader onUpload={() => {}} onRemove={() => {}} />
+        </div>
+
+        <div>
+          <h3 className="text-md font-semibold mb-3">첨부 파일</h3>
+          <div className="flex flex-col gap-3 mb-4">
+            <FileListItem
+              file={{ id: "1", name: "guide.pdf", size: "1.2MB" }}
+              onRemove={() => {}}
+            />
+          </div>
+          <FileUploader onFileSelect={() => {}} />
+        </div>
+      </div>
+    );
+  },
+};
diff --git a/src/shared/ui/file-uploader/file-uploader.tsx b/src/shared/ui/file-uploader/file-uploader.tsx
new file mode 100644
index 0000000..605c255
--- /dev/null
+++ b/src/shared/ui/file-uploader/file-uploader.tsx
@@ -0,0 +1,174 @@
+import React, { useRef } from "react";
+import { UploadIcon, ImageIcon, XIcon, FileTextIcon } from "@/shared/ui/icons";
+import { Button } from "@/shared/ui/button/button";
+
+// --- Types ---
+
+export type FileUploaderProps = {
+  label?: string;
+  accept?: string;
+  multiple?: boolean;
+  onFileSelect: (files: File[]) => void;
+  className?: string;
+};
+
+export type ThumbnailUploaderProps = {
+  previewUrl?: string;
+  onUpload: (file: File) => void;
+  onRemove: () => void;
+  className?: string;
+};
+
+export type FileItem = {
+  id: string;
+  name: string;
+  size: string;
+  type?: string;
+};
+
+export type FileListItemProps = {
+  file: FileItem;
+  onRemove: (id: string) => void;
+  className?: string;
+};
+
+// --- Styles ---
+
+const uploaderBaseClasses =
+  "flex flex-col items-center justify-center w-full border-2 border-dashed border-[var(--color-gray-300,#ccc)] rounded-lg cursor-pointer hover:bg-[var(--color-gray-50,#f9f9f9)] transition-colors duration-200 group";
+
+const getUploaderClasses = (heightClass: string, className?: string) => {
+  return [uploaderBaseClasses, heightClass, className].filter(Boolean).join(" ");
+};
+
+// --- Components ---
+
+// 1. Thumbnail Uploader (Large Image Upload)
+export const ThumbnailUploader = ({
+  previewUrl,
+  onUpload,
+  onRemove,
+  className,
+}: ThumbnailUploaderProps) => {
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  const handleClick = () => fileInputRef.current?.click();
+
+  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (file) onUpload(file);
+  };
+
+  if (previewUrl) {
+    return (
+      <div
+        className={[
+          "relative overflow-hidden rounded-lg w-full h-64 border border-[var(--color-gray-200,#e5e5ec)]",
+          className,
+        ].join(" ")}
+      >
+        <img src={previewUrl} alt="Thumbnail Preview" className="w-full h-full object-cover" />
+        <Button
+          variant="danger"
+          size="small"
+          className="absolute top-2 right-2 w-8 h-8 p-0"
+          onClick={onRemove}
+          aria-label="Remove image"
+        >
+          <XIcon size={16} />
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div className={getUploaderClasses("h-64", className)} onClick={handleClick}>
+      <input
+        type="file"
+        ref={fileInputRef}
+        className="hidden"
+        accept="image/*"
+        onChange={handleFileChange}
+      />
+      <div className="text-center">
+        <ImageIcon
+          size={48}
+          className="mx-auto mb-3 text-[var(--color-gray-400,#999)] group-hover:text-[var(--color-primary-500)] transition-colors"
+        />
+        <p className="text-[16px] font-medium text-[var(--color-gray-800,#333)]">
+          썸네일 이미지 업로드
+        </p>
+        <p className="text-[14px] text-[var(--color-gray-500,#666)] mt-1">
+          이미지를 드래그하거나 클릭하세요
+        </p>
+      </div>
+    </div>
+  );
+};
+
+// 2. File List Item (Uploaded file display)
+export const FileListItem = ({ file, onRemove, className }: FileListItemProps) => {
+  return (
+    <div
+      className={[
+        "flex items-center justify-between p-4 bg-white border border-[var(--color-gray-200,#e5e5ec)] rounded-lg hover:bg-[var(--color-gray-50,#f9f9f9)] transition-colors duration-200",
+        className,
+      ].join(" ")}
+    >
+      <div className="flex items-center gap-3">
+        <div className="text-[var(--color-gray-400,#999)]">
+          {file.type?.includes("image") ? <ImageIcon size={20} /> : <FileTextIcon size={20} />}
+        </div>
+        <div>
+          <p className="text-[14px] font-medium text-[var(--color-gray-800,#333)] truncate max-w-[200px]">
+            {file.name}
+          </p>
+          <p className="text-[12px] text-[var(--color-gray-500,#999)]">{file.size}</p>
+        </div>
+      </div>
+      <button
+        type="button"
+        onClick={() => onRemove(file.id)}
+        className="p-1.5 text-[var(--color-gray-400,#999)] hover:text-[var(--color-error-500,#ef4444)] transition-colors"
+        aria-label="Delete file"
+      >
+        <XIcon size={18} />
+      </button>
+    </div>
+  );
+};
+
+// 3. General Multi-file Uploader Area
+export const FileUploader = ({
+  onFileSelect,
+  accept,
+  multiple = true,
+  className,
+}: FileUploaderProps) => {
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const files = Array.from(e.target.files || []);
+    if (files.length > 0) onFileSelect(files);
+  };
+
+  return (
+    <div
+      className={getUploaderClasses("h-32", className)}
+      onClick={() => fileInputRef.current?.click()}
+    >
+      <input
+        type="file"
+        ref={fileInputRef}
+        className="hidden"
+        accept={accept}
+        multiple={multiple}
+        onChange={handleFileChange}
+      />
+      <div className="flex flex-col items-center">
+        <UploadIcon size={24} className="mb-2 text-[var(--color-gray-400,#999)]" />
+        <p className="text-[14px] font-medium text-[var(--color-gray-600,#666)]">파일 추가</p>
+      </div>
+    </div>
+  );
+};
diff --git a/src/shared/ui/file-uploader/index.ts b/src/shared/ui/file-uploader/index.ts
new file mode 100644
index 0000000..1709d47
--- /dev/null
+++ b/src/shared/ui/file-uploader/index.ts
@@ -0,0 +1 @@
+export * from "./file-uploader";

From 6885721e0311b3aad54b6e93cbfa646524ad1b90 Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 21 Mar 2026 19:28:32 +0900
Subject: [PATCH 05/15] =?UTF-8?q?[Refactor]=20shared/ui=20=ED=8F=BC=20?=
 =?UTF-8?q?=EA=B4=80=EB=A0=A8=20=EC=BB=B4=ED=8F=AC=EB=84=8C=ED=8A=B8=20?=
 =?UTF-8?q?=EB=82=B4=EB=B3=B4=EB=82=B4=EA=B8=B0=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/index.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/shared/ui/index.ts b/src/shared/ui/index.ts
index 1d96ba4..c6b560c 100644
--- a/src/shared/ui/index.ts
+++ b/src/shared/ui/index.ts
@@ -5,3 +5,8 @@ export { Pagination } from "./pagination/pagination";
 export type { PaginationProps } from "./pagination/pagination";
 export { Navigation } from "./navigation/navigation";
 export type { NavigationProps, NavItem, NavUser } from "./navigation/navigation";
+
+// Form components
+export * from "./form";
+export * from "./checkbox";
+export * from "./file-uploader";

From 49f73a2a893959acf09f4c1d5385d6735d35ae6d Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 21 Mar 2026 19:34:36 +0900
Subject: [PATCH 06/15] =?UTF-8?q?[Fix]=20=ED=97=A4=EB=8D=94=20=EC=9C=84?=
 =?UTF-8?q?=EC=A0=AF=20=EB=82=B4=EB=B3=B4=EB=82=B4=EA=B8=B0=20=EA=B2=BD?=
 =?UTF-8?q?=EB=A1=9C=20=EC=98=A4=EB=A5=98=20=EC=88=98=EC=A0=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/widgets/index.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/widgets/index.ts b/src/widgets/index.ts
index 7a8c43e..b59c177 100644
--- a/src/widgets/index.ts
+++ b/src/widgets/index.ts
@@ -1,2 +1 @@
 // Widgets barrel export
-export { Header } from "./header";

From 6246a5f0687c9fe40b45c0c595031a2367db5dab Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 28 Mar 2026 19:58:43 +0900
Subject: [PATCH 07/15] =?UTF-8?q?[Feat]=20=EA=B3=B5=ED=86=B5=20=EB=AA=A8?=
 =?UTF-8?q?=EB=8B=AC(Modal)=20=EA=B8=B0=EC=B4=88=20=EC=BB=B4=ED=8F=AC?=
 =?UTF-8?q?=EB=84=8C=ED=8A=B8=20=EC=8B=9C=EC=8A=A4=ED=85=9C=20=EA=B5=AC?=
 =?UTF-8?q?=ED=98=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/modal/index.ts  |   1 +
 src/shared/ui/modal/modal.tsx | 104 ++++++++++++++++++++++++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 src/shared/ui/modal/index.ts
 create mode 100644 src/shared/ui/modal/modal.tsx

diff --git a/src/shared/ui/modal/index.ts b/src/shared/ui/modal/index.ts
new file mode 100644
index 0000000..031608e
--- /dev/null
+++ b/src/shared/ui/modal/index.ts
@@ -0,0 +1 @@
+export * from "./modal";
diff --git a/src/shared/ui/modal/modal.tsx b/src/shared/ui/modal/modal.tsx
new file mode 100644
index 0000000..12c67a9
--- /dev/null
+++ b/src/shared/ui/modal/modal.tsx
@@ -0,0 +1,104 @@
+import React, { useEffect } from "react";
+import { createPortal } from "react-dom";
+import { XIcon } from "@/shared/ui/icons";
+
+// --- Types ---
+export type ModalProps = {
+  isOpen: boolean;
+  onClose: () => void;
+  children: React.ReactNode;
+  className?: string;
+};
+
+export type ModalHeaderProps = {
+  title?: string;
+  onClose?: () => void;
+  children?: React.ReactNode;
+  className?: string;
+};
+
+export type ModalContentProps = {
+  children: React.ReactNode;
+  className?: string;
+};
+
+export type ModalFooterProps = {
+  children: React.ReactNode;
+  className?: string;
+};
+
+// --- Styles ---
+
+// 1. Overlay
+const overlayBaseClasses =
+  "fixed inset-0 z-[100] bg-black/50 backdrop-blur-sm transition-opacity duration-300 flex items-center justify-center p-4";
+
+// 2. Modal Container
+const modalBaseClasses =
+  "bg-white rounded-xl shadow-xl w-full max-w-[600px] max-h-[90vh] flex flex-col overflow-hidden animate-in fade-in zoom-in-95 duration-200";
+
+// 3. Sections
+const headerBaseClasses =
+  "flex items-center justify-between px-6 py-4 border-b border-[var(--color-gray-100,#f2f2f2)]";
+const contentBaseClasses = "flex-1 overflow-y-auto px-6 py-6";
+const footerBaseClasses =
+  "px-6 py-4 border-t border-[var(--color-gray-100,#f2f2f2)] flex justify-end gap-2";
+
+const getModalClasses = (className?: string) =>
+  [modalBaseClasses, className].filter(Boolean).join(" ");
+
+// --- Components ---
+
+export const Modal = ({ isOpen, onClose, children, className }: ModalProps) => {
+  // ESC 키 대응 및 스크롤 잠금
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handleEsc = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+
+    document.body.style.overflow = "hidden";
+    window.addEventListener("keydown", handleEsc);
+
+    return () => {
+      document.body.style.overflow = "unset";
+      window.removeEventListener("keydown", handleEsc);
+    };
+  }, [isOpen, onClose]);
+
+  if (!isOpen) return null;
+
+  return createPortal(
+    <div className={overlayBaseClasses} onClick={(e) => e.target === e.currentTarget && onClose()}>
+      <div role="dialog" aria-modal="true" className={getModalClasses(className)}>
+        {children}
+      </div>
+    </div>,
+    document.body,
+  );
+};
+
+export const ModalHeader = ({ title, onClose, children, className }: ModalHeaderProps) => (
+  <div className={[headerBaseClasses, className].join(" ")}>
+    {title && <h2 className="text-[20px] font-bold text-[var(--color-gray-900,#111)]">{title}</h2>}
+    {children}
+    {onClose && (
+      <button
+        onClick={onClose}
+        className="p-1 rounded-md text-[var(--color-gray-400,#999)] hover:text-[var(--color-gray-600,#666)] hover:bg-[var(--color-gray-100,#f2f2f2)] transition-colors"
+        aria-label="Close modal"
+      >
+        <XIcon size={24} />
+      </button>
+    )}
+  </div>
+);
+
+export const ModalContent = ({ children, className }: ModalContentProps) => (
+  <div className={[contentBaseClasses, className].join(" ")}>{children}</div>
+);
+
+export const ModalFooter = ({ children, className }: ModalFooterProps) => (
+  <div className={[footerBaseClasses, className].join(" ")}>{children}</div>
+);

From 6fbbf2c4d4e749181c0333bcf9e1788e118fed62 Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 28 Mar 2026 19:59:31 +0900
Subject: [PATCH 08/15] =?UTF-8?q?[Feat]=20=EB=AA=A8=EB=8B=AC=20=ED=99=9C?=
 =?UTF-8?q?=EC=9A=A9=20=EC=98=88=EC=A0=9C(=ED=95=84=ED=84=B0,=20=ED=94=84?=
 =?UTF-8?q?=EB=A1=9C=ED=95=84=20=ED=8E=B8=EC=A7=91)=20=EB=B0=8F=20?=
 =?UTF-8?q?=EC=8A=A4=ED=86=A0=EB=A6=AC=EB=B6=81=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/modal/modal.stories.tsx | 148 ++++++++++++++++++++++++++
 1 file changed, 148 insertions(+)
 create mode 100644 src/shared/ui/modal/modal.stories.tsx

diff --git a/src/shared/ui/modal/modal.stories.tsx b/src/shared/ui/modal/modal.stories.tsx
new file mode 100644
index 0000000..b6beeea
--- /dev/null
+++ b/src/shared/ui/modal/modal.stories.tsx
@@ -0,0 +1,148 @@
+import React, { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Modal, ModalHeader, ModalContent, ModalFooter } from "./modal";
+import { Button } from "@/shared/ui/button/button";
+import { Checkbox } from "@/shared/ui/checkbox/checkbox";
+import { FormField, FormLabel } from "@/shared/ui/form";
+import { Input, Textarea, Select } from "@/shared/ui/inputBox/inputBox";
+
+const meta = {
+  title: "Shared/UI/Modal",
+  component: Modal,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof Modal>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// --- 1. Portfolio Filter Modal Example ---
+const FilterModalExample = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  const categories = ["웹 개발", "모바일 앱", "UI/UX 디자인", "데이터 분석", "AI/ML", "게임 개발"];
+  const departments = ["소프트웨어학과", "미디어학과", "산업공학과", "경영학과"];
+
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>필터 모달 열기</Button>
+      <Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
+        <ModalHeader title="필터 선택" onClose={() => setIsOpen(false)} />
+        <ModalContent className="space-y-8">
+          {/* 카테고리 섹션 */}
+          <div className="space-y-4">
+            <h3 className="text-[16px] font-semibold text-[var(--color-gray-800,#333)]">
+              카테고리
+            </h3>
+            <div className="grid grid-cols-2 gap-3">
+              <Checkbox label="전체" className="col-span-2" defaultChecked />
+              {categories.map((cat) => (
+                <Checkbox key={cat} label={cat} />
+              ))}
+            </div>
+          </div>
+
+          <div className="h-px bg-[var(--color-gray-100,#f2f2f2)]" />
+
+          {/* 학과 섹션 */}
+          <div className="space-y-4">
+            <h3 className="text-[16px] font-semibold text-[var(--color-gray-800,#333)]">학과</h3>
+            <div className="grid grid-cols-2 gap-3">
+              <Checkbox label="전체" className="col-span-2" defaultChecked />
+              {departments.map((dept) => (
+                <Checkbox key={dept} label={dept} />
+              ))}
+            </div>
+          </div>
+        </ModalContent>
+        <ModalFooter>
+          <Button variant="ghost" onClick={() => setIsOpen(false)}>
+            초기화
+          </Button>
+          <Button variant="secondary" onClick={() => setIsOpen(false)}>
+            취소
+          </Button>
+          <Button variant="primary" onClick={() => setIsOpen(false)} className="px-8">
+            적용
+          </Button>
+        </ModalFooter>
+      </Modal>
+    </>
+  );
+};
+
+export const FilterModal: Story = {
+  render: () => <FilterModalExample />,
+  args: {
+    isOpen: true,
+    onClose: () => {},
+    children: null,
+  },
+};
+
+// --- 2. Profile Edit Modal Example ---
+const ProfileEditModalExample = () => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button variant="secondary" onClick={() => setIsOpen(true)}>
+        프로필 편집 열기
+      </Button>
+      <Modal isOpen={isOpen} onClose={() => setIsOpen(false)} className="max-w-[500px]">
+        <ModalHeader title="프로필 편집" onClose={() => setIsOpen(false)} />
+        <ModalContent className="space-y-5">
+          <FormField>
+            <FormLabel>이름</FormLabel>
+            <Input defaultValue="김철수" />
+          </FormField>
+
+          <FormField>
+            <FormLabel>이메일</FormLabel>
+            <Input type="email" defaultValue="chulsoo.kim@ajou.ac.kr" />
+          </FormField>
+
+          <FormField>
+            <FormLabel>소속</FormLabel>
+            <Input defaultValue="아주대학교 소프트웨어학과" />
+          </FormField>
+
+          <FormField>
+            <FormLabel>회원 종류</FormLabel>
+            <Select
+              options={[
+                { label: "학생", value: "학생" },
+                { label: "교수", value: "교수" },
+                { label: "기업", value: "기업" },
+              ]}
+              defaultValue="학생"
+            />
+          </FormField>
+
+          <FormField>
+            <FormLabel>자기소개</FormLabel>
+            <Textarea defaultValue="웹 개발과 UI/UX 디자인에 관심이 많은 학생입니다." rows={4} />
+          </FormField>
+        </ModalContent>
+        <ModalFooter>
+          <Button variant="secondary" onClick={() => setIsOpen(false)}>
+            취소
+          </Button>
+          <Button variant="primary" onClick={() => setIsOpen(false)} className="px-8">
+            저장
+          </Button>
+        </ModalFooter>
+      </Modal>
+    </>
+  );
+};
+
+export const ProfileEditModal: Story = {
+  render: () => <ProfileEditModalExample />,
+  args: {
+    isOpen: true,
+    onClose: () => {},
+    children: null,
+  },
+};

From 7c9f23c5c92488b1de2f7aec0b5743dc45745ca4 Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 28 Mar 2026 19:59:47 +0900
Subject: [PATCH 09/15] =?UTF-8?q?[Refactor]=20shared/ui=20=EB=AA=A8?=
 =?UTF-8?q?=EB=8B=AC=20=EC=BB=B4=ED=8F=AC=EB=84=8C=ED=8A=B8=20=EB=82=B4?=
 =?UTF-8?q?=EB=B3=B4=EB=82=B4=EA=B8=B0=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/index.ts | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/shared/ui/index.ts b/src/shared/ui/index.ts
index 1d96ba4..2cd69bd 100644
--- a/src/shared/ui/index.ts
+++ b/src/shared/ui/index.ts
@@ -1,7 +1,15 @@
 export { Button } from "./button";
-export { Input } from "./input";
+export { Input, Textarea, Select } from "./inputBox/inputBox";
 export { DropdownMenu, SelectDropdown } from "./dropdown";
 export { Pagination } from "./pagination/pagination";
 export type { PaginationProps } from "./pagination/pagination";
 export { Navigation } from "./navigation/navigation";
 export type { NavigationProps, NavItem, NavUser } from "./navigation/navigation";
+
+// Form components
+export * from "./form";
+export * from "./checkbox";
+export * from "./file-uploader";
+
+// Modal components
+export * from "./modal";

From 93a890a28264421a42ca91674010ada327bf4126 Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 28 Mar 2026 20:16:23 +0900
Subject: [PATCH 10/15] =?UTF-8?q?[Feat]=20=EB=AA=A8=EB=8B=AC=20=ED=99=9C?=
 =?UTF-8?q?=EC=9A=A9=20=EC=98=88=EC=A0=9C(=ED=95=84=ED=84=B0,=20=ED=94=84?=
 =?UTF-8?q?=EB=A1=9C=ED=95=84=20=ED=8E=B8=EC=A7=91)=20=EA=B3=A0=EB=8F=84?=
 =?UTF-8?q?=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/modal/modal.stories.tsx | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/shared/ui/modal/modal.stories.tsx b/src/shared/ui/modal/modal.stories.tsx
index b6beeea..6c6ce63 100644
--- a/src/shared/ui/modal/modal.stories.tsx
+++ b/src/shared/ui/modal/modal.stories.tsx
@@ -30,7 +30,6 @@ const FilterModalExample = () => {
       <Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
         <ModalHeader title="필터 선택" onClose={() => setIsOpen(false)} />
         <ModalContent className="space-y-8">
-          {/* 카테고리 섹션 */}
           <div className="space-y-4">
             <h3 className="text-[16px] font-semibold text-[var(--color-gray-800,#333)]">
               카테고리
@@ -45,7 +44,6 @@ const FilterModalExample = () => {
 
           <div className="h-px bg-[var(--color-gray-100,#f2f2f2)]" />
 
-          {/* 학과 섹션 */}
           <div className="space-y-4">
             <h3 className="text-[16px] font-semibold text-[var(--color-gray-800,#333)]">학과</h3>
             <div className="grid grid-cols-2 gap-3">

From 1534fc49b487ec741422356fc881cebde9bd6167 Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 28 Mar 2026 20:18:04 +0900
Subject: [PATCH 11/15] =?UTF-8?q?[Fix]=20import=20React=20=EC=98=A4?=
 =?UTF-8?q?=EB=A5=98=20=EC=88=98=EC=A0=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/modal/modal.stories.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/shared/ui/modal/modal.stories.tsx b/src/shared/ui/modal/modal.stories.tsx
index 6c6ce63..ba62b61 100644
--- a/src/shared/ui/modal/modal.stories.tsx
+++ b/src/shared/ui/modal/modal.stories.tsx
@@ -1,4 +1,4 @@
-import React, { useState } from "react";
+import { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { Modal, ModalHeader, ModalContent, ModalFooter } from "./modal";
 import { Button } from "@/shared/ui/button/button";

From 49ce40b250b7594601baf1d571690bd0ef387d37 Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 28 Mar 2026 20:26:11 +0900
Subject: [PATCH 12/15] =?UTF-8?q?[Refactor]=20Checkbox=20=EC=A0=91?=
 =?UTF-8?q?=EA=B7=BC=EC=84=B1=20=EA=B0=9C=EC=84=A0=20=EB=B0=8F=20=EB=84=A4?=
 =?UTF-8?q?=EC=9D=B4=ED=8B=B0=EB=B8=8C=20=EC=83=81=ED=83=9C=20=EC=97=B0?=
 =?UTF-8?q?=EB=8F=99=20=EC=B5=9C=EC=A0=81=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/checkbox/checkbox.tsx | 63 ++++++++++-------------------
 1 file changed, 21 insertions(+), 42 deletions(-)

diff --git a/src/shared/ui/checkbox/checkbox.tsx b/src/shared/ui/checkbox/checkbox.tsx
index 97e911e..c0cc93c 100644
--- a/src/shared/ui/checkbox/checkbox.tsx
+++ b/src/shared/ui/checkbox/checkbox.tsx
@@ -8,61 +8,40 @@ export type CheckboxProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "t
 
 // --- Styles ---
 
-// 1. Container & Input
 const containerBaseClasses = "inline-flex items-center gap-2 cursor-pointer group select-none";
-const inputHiddenClasses = "sr-only"; // Screen reader only
 
-// 2. Checkbox Box
+// 체크박스 박스 스타일 (peer 상태에 반응 및 포커스 인디케이터 추가)
 const boxBaseClasses =
-  "w-5 h-5 flex items-center justify-center rounded border transition-all duration-200 ease-out shrink-0";
-
-const getBoxClasses = (checked?: boolean, disabled?: boolean) => {
-  if (disabled) {
-    return [
-      boxBaseClasses,
-      "bg-[var(--color-gray-100,#F2F2F2)] border-[var(--color-gray-200,#E5E5E5)]",
-    ].join(" ");
-  }
-  if (checked) {
-    return [
-      boxBaseClasses,
-      "bg-[var(--color-primary-800,#004A9C)] border-[var(--color-primary-800,#004A9C)]",
-    ].join(" ");
-  }
-  return [
-    boxBaseClasses,
-    "bg-white border-[var(--color-gray-300,#CCCCCC)] group-hover:border-[var(--color-primary-500,#3385DB)]",
-  ].join(" ");
-};
-
-// 3. Label
-const labelBaseClasses =
-  "text-[14px] leading-[1.43] tracking-[-0.35px] transition-colors duration-200";
-const getLabelClasses = (disabled?: boolean) => {
-  const statusClasses = disabled
+  "w-5 h-5 flex items-center justify-center rounded border transition-all duration-200 ease-out shrink-0 " +
+  "peer-focus-visible:ring-2 peer-focus-visible:ring-[var(--color-primary-200,#E0EDFB)] peer-focus-visible:ring-offset-1 " +
+  "peer-checked:bg-[var(--color-primary-800,#004A9C)] peer-checked:border-[var(--color-primary-800,#004A9C)] " +
+  "peer-checked:[&_svg]:scale-100 peer-checked:[&_svg]:opacity-100 " +
+  "peer-disabled:bg-[var(--color-gray-100,#F2F2F2)] peer-disabled:border-[var(--color-gray-200,#E5E5E5)] " +
+  "bg-white border-[var(--color-gray-300,#CCCCCC)] group-hover:peer-not-checked:border-[var(--color-primary-500,#3385DB)]";
+
+// 체크 아이콘 기본 스타일
+const iconClasses = "text-white transition-all duration-200 transform scale-0 opacity-0";
+
+// 라벨 스타일
+const labelClasses = (disabled?: boolean) => {
+  const base = "text-[14px] leading-[1.43] tracking-[-0.35px] transition-colors duration-200";
+  const status = disabled
     ? "text-[var(--color-gray-400,#999)]"
     : "text-[var(--color-gray-800,#333)]";
-  return [labelBaseClasses, statusClasses].join(" ");
+  return `${base} ${status}`;
 };
 
 // --- Component ---
 
 export const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
-  ({ label, checked, disabled, className = "", ...props }, ref) => {
+  ({ label, disabled, className = "", ...props }, ref) => {
     return (
       <label className={[containerBaseClasses, className].join(" ")}>
-        <input
-          type="checkbox"
-          ref={ref}
-          checked={checked}
-          disabled={disabled}
-          className={inputHiddenClasses}
-          {...props}
-        />
-        <div className={getBoxClasses(checked, disabled)}>
-          <CheckIcon size={14} className={checked ? "text-white" : "text-transparent"} />
+        <input type="checkbox" ref={ref} disabled={disabled} className="peer sr-only" {...props} />
+        <div className={boxBaseClasses}>
+          <CheckIcon size={14} className={iconClasses} />
         </div>
-        {label && <span className={getLabelClasses(disabled)}>{label}</span>}
+        {label && <span className={labelClasses(disabled)}>{label}</span>}
       </label>
     );
   },

From e605948198689bf7f21cdd79527b37a472ed30d1 Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 28 Mar 2026 20:26:49 +0900
Subject: [PATCH 13/15] =?UTF-8?q?[Feat]=20=ED=8C=8C=EC=9D=BC=20=EC=97=85?=
 =?UTF-8?q?=EB=A1=9C=EB=8D=94=20DND=20=EC=A7=80=EC=9B=90=20=EB=B0=8F=20For?=
 =?UTF-8?q?m=20=EC=8B=9C=EB=A7=A8=ED=8B=B1=20=EB=A7=88=ED=81=AC=EC=97=85?=
 =?UTF-8?q?=20=EC=B5=9C=EC=A0=81=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/file-uploader/file-uploader.tsx | 93 +++++++++++++++++--
 src/shared/ui/form/form.tsx                   | 17 +++-
 2 files changed, 97 insertions(+), 13 deletions(-)

diff --git a/src/shared/ui/file-uploader/file-uploader.tsx b/src/shared/ui/file-uploader/file-uploader.tsx
index 605c255..cea5f56 100644
--- a/src/shared/ui/file-uploader/file-uploader.tsx
+++ b/src/shared/ui/file-uploader/file-uploader.tsx
@@ -1,4 +1,4 @@
-import React, { useRef } from "react";
+import React, { useRef, useState } from "react";
 import { UploadIcon, ImageIcon, XIcon, FileTextIcon } from "@/shared/ui/icons";
 import { Button } from "@/shared/ui/button/button";
 
@@ -35,10 +35,14 @@ export type FileListItemProps = {
 // --- Styles ---
 
 const uploaderBaseClasses =
-  "flex flex-col items-center justify-center w-full border-2 border-dashed border-[var(--color-gray-300,#ccc)] rounded-lg cursor-pointer hover:bg-[var(--color-gray-50,#f9f9f9)] transition-colors duration-200 group";
+  "flex flex-col items-center justify-center w-full border-2 border-dashed rounded-lg cursor-pointer transition-colors duration-200 group outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary-200,#E0EDFB)] focus-visible:border-[var(--color-primary-500,#3385DB)]";
 
-const getUploaderClasses = (heightClass: string, className?: string) => {
-  return [uploaderBaseClasses, heightClass, className].filter(Boolean).join(" ");
+const getUploaderClasses = (heightClass: string, isDragging: boolean, className?: string) => {
+  const dragClasses = isDragging
+    ? "bg-[var(--color-primary-50,#EBF5FF)] border-[var(--color-primary-500,#3385DB)]"
+    : "bg-white border-[var(--color-gray-300,#ccc)] hover:bg-[var(--color-gray-50,#f9f9f9)]";
+
+  return [uploaderBaseClasses, heightClass, dragClasses, className].filter(Boolean).join(" ");
 };
 
 // --- Components ---
@@ -51,12 +55,37 @@ export const ThumbnailUploader = ({
   className,
 }: ThumbnailUploaderProps) => {
   const fileInputRef = useRef<HTMLInputElement>(null);
+  const [isDragging, setIsDragging] = useState(false);
 
   const handleClick = () => fileInputRef.current?.click();
 
   const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
     const file = e.target.files?.[0];
-    if (file) onUpload(file);
+    if (file) {
+      onUpload(file);
+      e.currentTarget.value = ""; // 동일 파일 업로드 가능하게 초기화
+    }
+  };
+
+  const handleDragOver = (e: React.DragEvent) => {
+    e.preventDefault();
+    setIsDragging(true);
+  };
+
+  const handleDragLeave = () => setIsDragging(false);
+
+  const handleDrop = (e: React.DragEvent) => {
+    e.preventDefault();
+    setIsDragging(false);
+    const file = e.dataTransfer.files?.[0];
+    if (file && file.type.startsWith("image/")) onUpload(file);
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      handleClick();
+    }
   };
 
   if (previewUrl) {
@@ -82,7 +111,17 @@ export const ThumbnailUploader = ({
   }
 
   return (
-    <div className={getUploaderClasses("h-64", className)} onClick={handleClick}>
+    <div
+      className={getUploaderClasses("h-64", isDragging, className)}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      onDragOver={handleDragOver}
+      onDragLeave={handleDragLeave}
+      onDrop={handleDrop}
+      role="button"
+      tabIndex={0}
+      aria-label="썸네일 이미지 업로드"
+    >
       <input
         type="file"
         ref={fileInputRef}
@@ -90,7 +129,7 @@ export const ThumbnailUploader = ({
         accept="image/*"
         onChange={handleFileChange}
       />
-      <div className="text-center">
+      <div className="text-center pointer-events-none">
         <ImageIcon
           size={48}
           className="mx-auto mb-3 text-[var(--color-gray-400,#999)] group-hover:text-[var(--color-primary-500)] transition-colors"
@@ -146,16 +185,48 @@ export const FileUploader = ({
   className,
 }: FileUploaderProps) => {
   const fileInputRef = useRef<HTMLInputElement>(null);
+  const [isDragging, setIsDragging] = useState(false);
 
   const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
     const files = Array.from(e.target.files || []);
+    if (files.length > 0) {
+      onFileSelect(files);
+      e.currentTarget.value = ""; // 초기화
+    }
+  };
+
+  const handleDragOver = (e: React.DragEvent) => {
+    e.preventDefault();
+    setIsDragging(true);
+  };
+
+  const handleDragLeave = () => setIsDragging(false);
+
+  const handleDrop = (e: React.DragEvent) => {
+    e.preventDefault();
+    setIsDragging(false);
+    const files = Array.from(e.dataTransfer.files || []);
     if (files.length > 0) onFileSelect(files);
   };
 
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      fileInputRef.current?.click();
+    }
+  };
+
   return (
     <div
-      className={getUploaderClasses("h-32", className)}
+      className={getUploaderClasses("h-32", isDragging, className)}
       onClick={() => fileInputRef.current?.click()}
+      onKeyDown={handleKeyDown}
+      onDragOver={handleDragOver}
+      onDragLeave={handleDragLeave}
+      onDrop={handleDrop}
+      role="button"
+      tabIndex={0}
+      aria-label="파일 추가"
     >
       <input
         type="file"
@@ -165,9 +236,11 @@ export const FileUploader = ({
         multiple={multiple}
         onChange={handleFileChange}
       />
-      <div className="flex flex-col items-center">
+      <div className="flex flex-col items-center pointer-events-none">
         <UploadIcon size={24} className="mb-2 text-[var(--color-gray-400,#999)]" />
-        <p className="text-[14px] font-medium text-[var(--color-gray-600,#666)]">파일 추가</p>
+        <p className="text-[14px] font-medium text-[var(--color-gray-600,#666)]">
+          파일을 드래그하거나 클릭하여 추가
+        </p>
       </div>
     </div>
   );
diff --git a/src/shared/ui/form/form.tsx b/src/shared/ui/form/form.tsx
index bddf220..745a6fe 100644
--- a/src/shared/ui/form/form.tsx
+++ b/src/shared/ui/form/form.tsx
@@ -54,12 +54,23 @@ export const FormField = ({ children, className }: FormFieldProps) => {
 };
 
 export const FormLabel = ({ children, required, htmlFor, className }: FormLabelProps) => {
-  return (
-    <label htmlFor={htmlFor} className={getLabelClasses(className)}>
+  const content = (
+    <>
       {children}
       {required && <span className="text-[var(--color-error-500,#EF4444)] ml-0.5">*</span>}
-    </label>
+    </>
   );
+
+  // htmlFor가 있으면 label, 없으면 span으로 렌더링
+  if (htmlFor) {
+    return (
+      <label htmlFor={htmlFor} className={getLabelClasses(className)}>
+        {content}
+      </label>
+    );
+  }
+
+  return <span className={getLabelClasses(className)}>{content}</span>;
 };
 
 export const FormHelperText = ({ children, className }: FormHelperTextProps) => {

From ba03d4798ce14688ba5622946257935d64a0db5f Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Sat, 28 Mar 2026 20:27:08 +0900
Subject: [PATCH 14/15] =?UTF-8?q?[Feat]=20=ED=8F=BC=20=EA=B4=80=EB=A0=A8?=
 =?UTF-8?q?=20=EC=8A=A4=ED=86=A0=EB=A6=AC=EB=B6=81=20=EC=9D=B8=ED=84=B0?=
 =?UTF-8?q?=EB=9E=99=EC=85=98=20=EB=B3=B4=EA=B0=95=20=EB=B0=8F=20=ED=83=80?=
 =?UTF-8?q?=EC=9E=85=20=EC=88=98=EC=A0=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/form/form.stories.tsx | 53 +++++++++++------------------
 1 file changed, 19 insertions(+), 34 deletions(-)

diff --git a/src/shared/ui/form/form.stories.tsx b/src/shared/ui/form/form.stories.tsx
index ec0cf20..06c5498 100644
--- a/src/shared/ui/form/form.stories.tsx
+++ b/src/shared/ui/form/form.stories.tsx
@@ -7,6 +7,7 @@ import {
   ThumbnailUploader,
   FileListItem,
   FileUploader,
+  type FileItem,
 } from "@/shared/ui/file-uploader/file-uploader";
 import { Button } from "@/shared/ui/button/button";
 
@@ -25,13 +26,26 @@ type Story = StoryObj<typeof meta>;
 // --- 종합 폼 예시 (포트폴리오 작성) ---
 const PortfolioCreateForm = () => {
   const [preview, setPreview] = useState<string | undefined>();
-  const [files, setFiles] = useState([
+  const [files, setFiles] = useState<FileItem[]>([
     { id: "1", name: "기획서_최종.pdf", size: "1.2 MB", type: "application/pdf" },
   ]);
 
+  const handleFileSelect = (newFiles: File[]) => {
+    const mappedFiles: FileItem[] = newFiles.map((file) => ({
+      id: Math.random().toString(36).substr(2, 9),
+      name: file.name,
+      size: `${(file.size / (1024 * 1024)).toFixed(1)} MB`,
+      type: file.type,
+    }));
+    setFiles((prev) => [...prev, ...mappedFiles]);
+  };
+
+  const removeFile = (id: string) => {
+    setFiles((prev) => prev.filter((f) => f.id !== id));
+  };
+
   return (
     <div className="w-[640px] flex flex-col gap-10 bg-white p-10 border rounded-2xl shadow-sm my-10">
-      {/* Header */}
       <div>
         <h1 className="text-[32px] font-bold text-[var(--color-gray-900,#111)] mb-2">
           포트폴리오 작성
@@ -41,7 +55,6 @@ const PortfolioCreateForm = () => {
         </p>
       </div>
 
-      {/* Basic Info Section */}
       <section className="flex flex-col gap-6">
         <h2 className="text-[20px] font-semibold text-[var(--color-gray-800,#333)] border-b pb-2">
           기본 정보
@@ -57,20 +70,8 @@ const PortfolioCreateForm = () => {
           <Textarea placeholder="프로젝트를 2-3줄로 요약해 주세요" rows={3} />
           <FormHelperText>목록 페이지에서 카드 설명으로 사용됩니다.</FormHelperText>
         </FormField>
-
-        <div className="flex gap-4">
-          <FormField className="flex-1">
-            <FormLabel>기술 스택</FormLabel>
-            <Input placeholder="예: React, TypeScript" />
-          </FormField>
-          <FormField className="flex-1">
-            <FormLabel>역할</FormLabel>
-            <Input placeholder="예: 프론트엔드 개발" />
-          </FormField>
-        </div>
       </section>
 
-      {/* Media Section */}
       <section className="flex flex-col gap-6">
         <h2 className="text-[20px] font-semibold text-[var(--color-gray-800,#333)] border-b pb-2">
           미디어 및 파일
@@ -83,38 +84,24 @@ const PortfolioCreateForm = () => {
             onUpload={() => setPreview("https://picsum.photos/800/400")}
             onRemove={() => setPreview(undefined)}
           />
-          <FormHelperText>권장 해상도: 1200 x 630 (1.91:1)</FormHelperText>
         </FormField>
 
         <FormField>
           <FormLabel>첨부 파일</FormLabel>
           <div className="flex flex-col gap-3 mb-4">
             {files.map((file) => (
-              <FileListItem
-                key={file.id}
-                file={file}
-                onRemove={(id) => setFiles(files.filter((f) => f.id !== id))}
-              />
+              <FileListItem key={file.id} file={file} onRemove={removeFile} />
             ))}
           </div>
-          <FileUploader onFileSelect={() => {}} />
+          <FileUploader onFileSelect={handleFileSelect} />
         </FormField>
       </section>
 
-      {/* Policy Section */}
       <section className="bg-[var(--color-gray-50)] p-6 rounded-xl flex flex-col gap-4">
-        <Checkbox label="위 프로젝트 내용이 사실임을 확인하며, 아주대학교 포트폴리오 운영 정책에 동의합니다." />
-        <Checkbox
-          label="프로젝트를 전체 공개로 설정합니다. (체크 해제 시 나만 보기)"
-          defaultChecked
-        />
+        <Checkbox label="운영 정책에 동의합니다." />
       </section>
 
-      {/* Footer Buttons */}
       <div className="flex justify-end gap-3 pt-6 border-t">
-        <Button variant="ghost" size="large" className="px-8">
-          임시 저장
-        </Button>
         <Button variant="primary" size="large" className="px-10">
           작성 완료
         </Button>
@@ -130,14 +117,12 @@ export const FullPortfolioForm: Story = {
   },
 };
 
-// --- 기존 개별 스토리 ---
 export const Default: Story = {
   render: () => (
     <div className="w-[400px]">
       <FormField>
         <FormLabel required>프로젝트 제목</FormLabel>
         <Input placeholder="프로젝트 제목을 입력하세요" />
-        <FormHelperText>다른 사람들이 쉽게 알 수 있는 제목을 정해주세요.</FormHelperText>
       </FormField>
     </div>
   ),

From 48e33cb39025539519c633ec6c53ae869f361328 Mon Sep 17 00:00:00 2001
From: kimsman <kimjaejun10@gmail.com>
Date: Wed, 1 Apr 2026 10:30:21 +0900
Subject: [PATCH 15/15] =?UTF-8?q?[Fix]=20=EB=AA=A8=EB=8B=AC=20=EC=8A=A4?=
 =?UTF-8?q?=ED=86=A0=EB=A6=AC=EB=B6=81=20=ED=95=84=EC=88=98=20Args(childre?=
 =?UTF-8?q?n)=20=EB=88=84=EB=9D=BD=EC=9C=BC=EB=A1=9C=20=EC=9D=B8=ED=95=9C?=
 =?UTF-8?q?=20=EB=B9=8C=EB=93=9C=20=EC=97=90=EB=9F=AC=20=EC=88=98=EC=A0=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/modal/modal.stories.tsx | 65 +++++++++++++++++----------
 src/shared/ui/modal/modal.tsx         | 63 +++++++++++++++++++-------
 2 files changed, 89 insertions(+), 39 deletions(-)

diff --git a/src/shared/ui/modal/modal.stories.tsx b/src/shared/ui/modal/modal.stories.tsx
index ba62b61..2d0568a 100644
--- a/src/shared/ui/modal/modal.stories.tsx
+++ b/src/shared/ui/modal/modal.stories.tsx
@@ -19,16 +19,25 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 // --- 1. Portfolio Filter Modal Example ---
-const FilterModalExample = () => {
-  const [isOpen, setIsOpen] = useState(false);
+const FilterModalExample = ({
+  isOpen: propsIsOpen,
+  onClose: propsOnClose,
+}: {
+  isOpen?: boolean;
+  onClose?: () => void;
+}) => {
+  const [internalIsOpen, setInternalIsOpen] = useState(false);
+  const isOpen = propsIsOpen ?? internalIsOpen;
+  const onClose = propsOnClose ?? (() => setInternalIsOpen(false));
+
   const categories = ["웹 개발", "모바일 앱", "UI/UX 디자인", "데이터 분석", "AI/ML", "게임 개발"];
   const departments = ["소프트웨어학과", "미디어학과", "산업공학과", "경영학과"];
 
   return (
     <>
-      <Button onClick={() => setIsOpen(true)}>필터 모달 열기</Button>
-      <Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
-        <ModalHeader title="필터 선택" onClose={() => setIsOpen(false)} />
+      {!propsIsOpen && <Button onClick={() => setInternalIsOpen(true)}>필터 모달 열기</Button>}
+      <Modal isOpen={isOpen} onClose={onClose}>
+        <ModalHeader title="필터 선택" onClose={onClose} />
         <ModalContent className="space-y-8">
           <div className="space-y-4">
             <h3 className="text-[16px] font-semibold text-[var(--color-gray-800,#333)]">
@@ -55,13 +64,13 @@ const FilterModalExample = () => {
           </div>
         </ModalContent>
         <ModalFooter>
-          <Button variant="ghost" onClick={() => setIsOpen(false)}>
+          <Button variant="ghost" onClick={onClose}>
             초기화
           </Button>
-          <Button variant="secondary" onClick={() => setIsOpen(false)}>
+          <Button variant="secondary" onClick={onClose}>
             취소
           </Button>
-          <Button variant="primary" onClick={() => setIsOpen(false)} className="px-8">
+          <Button variant="primary" onClick={onClose} className="px-8">
             적용
           </Button>
         </ModalFooter>
@@ -71,25 +80,35 @@ const FilterModalExample = () => {
 };
 
 export const FilterModal: Story = {
-  render: () => <FilterModalExample />,
+  render: (args) => <FilterModalExample {...args} />,
   args: {
-    isOpen: true,
+    isOpen: false,
     onClose: () => {},
-    children: null,
+    children: null, // 필수 속성 추가
   },
 };
 
 // --- 2. Profile Edit Modal Example ---
-const ProfileEditModalExample = () => {
-  const [isOpen, setIsOpen] = useState(false);
+const ProfileEditModalExample = ({
+  isOpen: propsIsOpen,
+  onClose: propsOnClose,
+}: {
+  isOpen?: boolean;
+  onClose?: () => void;
+}) => {
+  const [internalIsOpen, setInternalIsOpen] = useState(false);
+  const isOpen = propsIsOpen ?? internalIsOpen;
+  const onClose = propsOnClose ?? (() => setInternalIsOpen(false));
 
   return (
     <>
-      <Button variant="secondary" onClick={() => setIsOpen(true)}>
-        프로필 편집 열기
-      </Button>
-      <Modal isOpen={isOpen} onClose={() => setIsOpen(false)} className="max-w-[500px]">
-        <ModalHeader title="프로필 편집" onClose={() => setIsOpen(false)} />
+      {!propsIsOpen && (
+        <Button variant="secondary" onClick={() => setInternalIsOpen(true)}>
+          프로필 편집 열기
+        </Button>
+      )}
+      <Modal isOpen={isOpen} onClose={onClose} className="max-w-[500px]">
+        <ModalHeader title="프로필 편집" onClose={onClose} />
         <ModalContent className="space-y-5">
           <FormField>
             <FormLabel>이름</FormLabel>
@@ -124,10 +143,10 @@ const ProfileEditModalExample = () => {
           </FormField>
         </ModalContent>
         <ModalFooter>
-          <Button variant="secondary" onClick={() => setIsOpen(false)}>
+          <Button variant="secondary" onClick={onClose}>
             취소
           </Button>
-          <Button variant="primary" onClick={() => setIsOpen(false)} className="px-8">
+          <Button variant="primary" onClick={onClose} className="px-8">
             저장
           </Button>
         </ModalFooter>
@@ -137,10 +156,10 @@ const ProfileEditModalExample = () => {
 };
 
 export const ProfileEditModal: Story = {
-  render: () => <ProfileEditModalExample />,
+  render: (args) => <ProfileEditModalExample {...args} />,
   args: {
-    isOpen: true,
+    isOpen: false,
     onClose: () => {},
-    children: null,
+    children: null, // 필수 속성 추가
   },
 };
diff --git a/src/shared/ui/modal/modal.tsx b/src/shared/ui/modal/modal.tsx
index 12c67a9..9122e77 100644
--- a/src/shared/ui/modal/modal.tsx
+++ b/src/shared/ui/modal/modal.tsx
@@ -1,13 +1,18 @@
-import React, { useEffect } from "react";
+import React, { useEffect, useId } from "react";
 import { createPortal } from "react-dom";
 import { XIcon } from "@/shared/ui/icons";
 
+// --- Global State for Nested Modals ---
+let modalOpenCount = 0;
+let originalOverflow = "";
+
 // --- Types ---
 export type ModalProps = {
   isOpen: boolean;
   onClose: () => void;
   children: React.ReactNode;
   className?: string;
+  titleId?: string; // 접근성을 위한 ID
 };
 
 export type ModalHeaderProps = {
@@ -15,6 +20,7 @@ export type ModalHeaderProps = {
   onClose?: () => void;
   children?: React.ReactNode;
   className?: string;
+  id?: string; // h2에 부여될 ID
 };
 
 export type ModalContentProps = {
@@ -29,59 +35,84 @@ export type ModalFooterProps = {
 
 // --- Styles ---
 
-// 1. Overlay
 const overlayBaseClasses =
   "fixed inset-0 z-[100] bg-black/50 backdrop-blur-sm transition-opacity duration-300 flex items-center justify-center p-4";
 
-// 2. Modal Container
 const modalBaseClasses =
   "bg-white rounded-xl shadow-xl w-full max-w-[600px] max-h-[90vh] flex flex-col overflow-hidden animate-in fade-in zoom-in-95 duration-200";
 
-// 3. Sections
 const headerBaseClasses =
   "flex items-center justify-between px-6 py-4 border-b border-[var(--color-gray-100,#f2f2f2)]";
 const contentBaseClasses = "flex-1 overflow-y-auto px-6 py-6";
 const footerBaseClasses =
   "px-6 py-4 border-t border-[var(--color-gray-100,#f2f2f2)] flex justify-end gap-2";
 
-const getModalClasses = (className?: string) =>
-  [modalBaseClasses, className].filter(Boolean).join(" ");
+const getClasses = (...classes: (string | undefined)[]) => classes.filter(Boolean).join(" ");
 
 // --- Components ---
 
 export const Modal = ({ isOpen, onClose, children, className }: ModalProps) => {
-  // ESC 키 대응 및 스크롤 잠금
+  const generatedId = useId();
+  const titleId = `modal-title-${generatedId}`;
+
   useEffect(() => {
     if (!isOpen) return;
 
+    // ESC 키 대응
     const handleEsc = (e: KeyboardEvent) => {
       if (e.key === "Escape") onClose();
     };
 
-    document.body.style.overflow = "hidden";
+    // 스크롤 잠금 (중첩 모달 대응)
+    if (modalOpenCount === 0) {
+      originalOverflow = document.body.style.overflow;
+      document.body.style.overflow = "hidden";
+    }
+    modalOpenCount++;
+
     window.addEventListener("keydown", handleEsc);
 
     return () => {
-      document.body.style.overflow = "unset";
+      modalOpenCount--;
+      if (modalOpenCount === 0) {
+        document.body.style.overflow = originalOverflow;
+      }
       window.removeEventListener("keydown", handleEsc);
     };
   }, [isOpen, onClose]);
 
   if (!isOpen) return null;
 
+  // 자식 요소들에 titleId를 주입하기 위해 React.Children.map 사용 (ModalHeader 탐색)
+  const childrenWithA11y = React.Children.map(children, (child) => {
+    if (React.isValidElement(child) && child.type === ModalHeader) {
+      return React.cloneElement(child as React.ReactElement<ModalHeaderProps>, { id: titleId });
+    }
+    return child;
+  });
+
   return createPortal(
     <div className={overlayBaseClasses} onClick={(e) => e.target === e.currentTarget && onClose()}>
-      <div role="dialog" aria-modal="true" className={getModalClasses(className)}>
-        {children}
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={titleId}
+        className={getClasses(modalBaseClasses, className)}
+      >
+        {childrenWithA11y}
       </div>
     </div>,
     document.body,
   );
 };
 
-export const ModalHeader = ({ title, onClose, children, className }: ModalHeaderProps) => (
-  <div className={[headerBaseClasses, className].join(" ")}>
-    {title && <h2 className="text-[20px] font-bold text-[var(--color-gray-900,#111)]">{title}</h2>}
+export const ModalHeader = ({ title, onClose, children, className, id }: ModalHeaderProps) => (
+  <div className={getClasses(headerBaseClasses, className)}>
+    {title && (
+      <h2 id={id} className="text-[20px] font-bold text-[var(--color-gray-900,#111)]">
+        {title}
+      </h2>
+    )}
     {children}
     {onClose && (
       <button
@@ -96,9 +127,9 @@ export const ModalHeader = ({ title, onClose, children, className }: ModalHeader
 );
 
 export const ModalContent = ({ children, className }: ModalContentProps) => (
-  <div className={[contentBaseClasses, className].join(" ")}>{children}</div>
+  <div className={getClasses(contentBaseClasses, className)}>{children}</div>
 );
 
 export const ModalFooter = ({ children, className }: ModalFooterProps) => (
-  <div className={[footerBaseClasses, className].join(" ")}>{children}</div>
+  <div className={getClasses(footerBaseClasses, className)}>{children}</div>
 );