From 55b5a06ae97d91c69c7e3678e2130e4fed3e498c Mon Sep 17 00:00:00 2001
From: Kazunari Hara <kz.route21@gmail.com>
Date: Fri, 27 Mar 2026 11:39:28 +0900
Subject: [PATCH] docs(spindle-ui): add story descriptions and props table for
 Button

---
 packages/spindle-ui/.storybook/main.js        |  2 +-
 packages/spindle-ui/src/Button/Button.mdx     | 28 ++++++++++++++-
 .../spindle-ui/src/Button/Button.stories.tsx  | 35 +++++++++++++++++++
 packages/spindle-ui/src/Button/Button.tsx     |  5 +++
 4 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/packages/spindle-ui/.storybook/main.js b/packages/spindle-ui/.storybook/main.js
index 5c5b1676c..43f9abe5f 100644
--- a/packages/spindle-ui/.storybook/main.js
+++ b/packages/spindle-ui/.storybook/main.js
@@ -21,6 +21,6 @@ module.exports = {
     name: '@storybook/react-webpack5',
   },
   typescript: {
-    reactDocgen: false,
+    reactDocgen: 'react-docgen-typescript',
   },
 };
diff --git a/packages/spindle-ui/src/Button/Button.mdx b/packages/spindle-ui/src/Button/Button.mdx
index 8b9537fbc..60f7fda52 100644
--- a/packages/spindle-ui/src/Button/Button.mdx
+++ b/packages/spindle-ui/src/Button/Button.mdx
@@ -1,10 +1,12 @@
-import { Meta, Story, Source } from '@storybook/addon-docs/blocks';
+import { Meta, Story, Source, ArgTypes, Description } from '@storybook/addon-docs/blocks';
 import * as ButtonStories from './Button.stories';
 
 <Meta of={ButtonStories} />
 
 # Button
 
+<Description of={ButtonStories} />
+
 <Source
   language='javascript'
   code={`
@@ -23,8 +25,14 @@ import '@openameba/spindle-ui/Button/Button.css';
   code={`<link rel="stylesheet" href="https://unpkg.com/@openameba/spindle-ui/Button/Button.css">`}
 />
 
+## Props
+
+<ArgTypes of={ButtonStories} />
+
 ## Large
 
+<Description of={ButtonStories.Large} />
+
 <Story of={ButtonStories.Large} />
 
 <Source
@@ -50,6 +58,8 @@ import '@openameba/spindle-ui/Button/Button.css';
 
 ## Large Full Width
 
+<Description of={ButtonStories.LargeFullWidth} />
+
 <Story of={ButtonStories.LargeFullWidth} />
 
 <Source
@@ -75,6 +85,8 @@ import '@openameba/spindle-ui/Button/Button.css';
 
 ## Medium
 
+<Description of={ButtonStories.Medium} />
+
 <Story of={ButtonStories.Medium} />
 
 <Source
@@ -100,6 +112,8 @@ import '@openameba/spindle-ui/Button/Button.css';
 
 ## Medium Full Width
 
+<Description of={ButtonStories.MediumFullWidth} />
+
 <Story of={ButtonStories.MediumFullWidth} />
 
 <Source
@@ -125,6 +139,8 @@ import '@openameba/spindle-ui/Button/Button.css';
 
 ## Small
 
+<Description of={ButtonStories.Small} />
+
 <Story of={ButtonStories.Small} />
 
 <Source
@@ -150,6 +166,8 @@ import '@openameba/spindle-ui/Button/Button.css';
 
 ## Small Full Width
 
+<Description of={ButtonStories.SmallFullWidth} />
+
 <Story of={ButtonStories.SmallFullWidth} />
 
 <Source
@@ -175,6 +193,8 @@ import '@openameba/spindle-ui/Button/Button.css';
 
 ## Disabled
 
+<Description of={ButtonStories.Disabled} />
+
 <Story of={ButtonStories.Disabled} />
 
 <Source
@@ -200,6 +220,8 @@ import '@openameba/spindle-ui/Button/Button.css';
 
 ## Disabled Full Width
 
+<Description of={ButtonStories.DisabledFullWidth} />
+
 <Story of={ButtonStories.DisabledFullWidth} />
 
 <Source
@@ -225,6 +247,8 @@ import '@openameba/spindle-ui/Button/Button.css';
 
 ## With Icon
 
+<Description of={ButtonStories.WithIcon} />
+
 <Story of={ButtonStories.WithIcon} />
 
 <Source
@@ -252,6 +276,8 @@ import '@openameba/spindle-ui/Button/Button.css';
 
 ## Full Width With Icon
 
+<Description of={ButtonStories.FullWidthWithIcon} />
+
 <Story of={ButtonStories.FullWidthWithIcon} />
 
 <Source
diff --git a/packages/spindle-ui/src/Button/Button.stories.tsx b/packages/spindle-ui/src/Button/Button.stories.tsx
index 1bf3da833..630b8af5c 100644
--- a/packages/spindle-ui/src/Button/Button.stories.tsx
+++ b/packages/spindle-ui/src/Button/Button.stories.tsx
@@ -4,8 +4,13 @@ import { action } from 'storybook/actions';
 import { ChevronDownBold, FileAdd, Link, PlusBold } from '../Icon';
 import { Button } from './Button';
 
+/**
+ * ユーザーのアクションを実行するためのボタンコンポーネント。
+ * contained, outlined, neutral, danger, lighted の5つのバリアントを持つ。
+ */
 const meta: Meta<typeof Button> = {
   title: 'Button',
+  component: Button,
   args: {
     onClick: action('clicked'),
     onMouseOver: action('mouse-over'),
@@ -15,6 +20,9 @@ const meta: Meta<typeof Button> = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+/**
+ * Large サイズのボタン。画面の主要アクションなど、視認性を高めたい場合に使用する。
+ */
 export const Large: Story = {
   render: (args) => (
     <>
@@ -37,6 +45,9 @@ export const Large: Story = {
   ),
 };
 
+/**
+ * Large サイズの全幅ボタン。モバイル画面下部の固定ボタンなどに使用する。
+ */
 export const LargeFullWidth: Story = {
   render: (args) => (
     <>
@@ -59,6 +70,9 @@ export const LargeFullWidth: Story = {
   ),
 };
 
+/**
+ * Medium サイズのボタン。もっとも汎用的なサイズ。
+ */
 export const Medium: Story = {
   render: (args) => (
     <>
@@ -81,6 +95,9 @@ export const Medium: Story = {
   ),
 };
 
+/**
+ * Medium サイズの全幅ボタン。
+ */
 export const MediumFullWidth: Story = {
   render: (args) => (
     <>
@@ -103,6 +120,9 @@ export const MediumFullWidth: Story = {
   ),
 };
 
+/**
+ * Small サイズのボタン。補助的なアクションやスペースが限られた箇所に使用する。
+ */
 export const Small: Story = {
   render: (args) => (
     <>
@@ -125,6 +145,9 @@ export const Small: Story = {
   ),
 };
 
+/**
+ * Small サイズの全幅ボタン。
+ */
 export const SmallFullWidth: Story = {
   render: (args) => (
     <>
@@ -147,6 +170,9 @@ export const SmallFullWidth: Story = {
   ),
 };
 
+/**
+ * 非活性状態のボタン。処理中やバリデーションエラー時など、操作を防ぎたい場合に使用する。
+ */
 export const Disabled: Story = {
   render: (args) => (
     <>
@@ -169,6 +195,9 @@ export const Disabled: Story = {
   ),
 };
 
+/**
+ * 非活性状態の全幅ボタン。
+ */
 export const DisabledFullWidth: Story = {
   render: (args) => (
     <>
@@ -221,6 +250,9 @@ export const DisabledFullWidth: Story = {
   ),
 };
 
+/**
+ * アイコン付きボタン。テキストだけでは伝わりにくいアクションの意味を補強する場合に使用する。
+ */
 export const WithIcon: Story = {
   render: (args) => (
     <>
@@ -264,6 +296,9 @@ export const WithIcon: Story = {
   ),
 };
 
+/**
+ * アイコン付き全幅ボタン。
+ */
 export const FullWidthWithIcon: Story = {
   render: (args) => (
     <>
diff --git a/packages/spindle-ui/src/Button/Button.tsx b/packages/spindle-ui/src/Button/Button.tsx
index 9a8b81fb9..e1ee3953e 100644
--- a/packages/spindle-ui/src/Button/Button.tsx
+++ b/packages/spindle-ui/src/Button/Button.tsx
@@ -9,10 +9,15 @@ type Variant = 'contained' | 'outlined' | 'lighted' | 'neutral' | 'danger';
 interface Props
   extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'className'> {
   children?: React.ReactNode;
+  /** ボタンの横幅。fullWidth で親要素いっぱいに広がる */
   layout?: Layout;
+  /** ボタンの大きさ */
   size?: Size;
+  /** ボタンの見た目。アクションの重要度に応じて使い分ける */
   variant?: Variant;
+  /** ボタンテキストの前後に表示するアイコン */
   icon?: React.ReactNode;
+  /** アイコンの表示位置 */
   iconPosition?: 'start' | 'end';
 }