chore: Storybook deploy comment in English

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jungcome7

.github/workflows/deploy-storybook.yml

@@ -58,7 +58,7 @@ jobs:
         with:
           issue-number: ${{ github.event.pull_request.number }}
           comment-author: "github-actions[bot]"
-          body-includes: "Storybook 배포 완료"
+          body-includes: "Storybook Deployed"
 
       - name: Create or update deployment comment
         if: github.event_name == 'pull_request'
@@ -67,9 +67,9 @@ jobs:
           comment-id: ${{ steps.find-comment.outputs.comment-id }}
           issue-number: ${{ github.event.pull_request.number }}
           body: |
-            ## Storybook 배포 완료
+            ## Storybook Deployed
 
-            :link: **미리보기:** ${{ steps.deployment.outputs.page_url }}storybook/
+            :link: **Preview:** ${{ steps.deployment.outputs.page_url }}storybook/
 
             _Last updated: ${{ github.event.pull_request.updated_at }}_
           edit-mode: replace

packages/design-system/.storybook/main.ts

@@ -3,7 +3,7 @@ import type { StorybookConfig } from "@storybook/react-vite";
 const config: StorybookConfig = {
   framework: "@storybook/react-vite",
   stories: ["../src/**/*.stories.@(ts|tsx)"],
-  addons: ["@storybook/addon-themes"],
+  addons: ["@storybook/addon-docs", "@storybook/addon-themes"],
 };
 
 export default config;

packages/design-system/.storybook/preview.tsx

@@ -6,21 +6,31 @@ import { DSColor } from "../src/foundation/color";
 const preview: Preview = {
   parameters: {
     layout: "fullscreen",
+    options: {
+      storySort: {
+        order: [
+          "Foundations",
+          ["Color", "Icon", "Typography", ["Docs", "Showcase", "Playground"]],
+          "Components",
+        ],
+      },
+    },
   },
   initialGlobals: {
     theme: "light",
   },
   decorators: [
     (Story, context) => {
       const theme = (context.globals["theme"] as "dark" | "light") || "light";
+      const isDocs = context.viewMode === "docs";
       return (
         <DSThemeProvider defaultTheme={theme}>
           <div
             style={{
               backgroundColor: DSColor.background.surface.ground,
               color: DSColor.typography.primary,
-              padding: 40,
-              minHeight: "100vh",
+              padding: isDocs ? 16 : 40,
+              minHeight: isDocs ? undefined : "100vh",
               fontFamily: "Inter, sans-serif",
             }}
           >

packages/design-system/package.json

@@ -23,6 +23,7 @@
     "sync:tokens": "node scripts/sync-tokens/sync-all.mjs"
   },
   "devDependencies": {
+    "@storybook/addon-docs": "^10.3.3",
     "@storybook/addon-themes": "^10.3.3",
     "@storybook/react": "^10.3.3",
     "@storybook/react-vite": "^10.3.3",

packages/design-system/src/components/components.stories.tsx

@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from "@storybook/react";
+
+const font = "Inter, -apple-system, sans-serif";
+
+const meta = {
+  title: "Components/Overview",
+} satisfies Meta;
+
+export default meta;
+
+export const Overview: StoryObj = {
+  name: "Overview",
+  render: () => (
+    <div
+      style={{
+        fontFamily: font,
+        display: "flex",
+        flexDirection: "column",
+        gap: 8,
+      }}
+    >
+      <h1
+        style={{
+          fontFamily: font,
+          fontSize: 28,
+          fontWeight: 600,
+          margin: "0 0 8px",
+          lineHeight: 1.4,
+        }}
+      >
+        Components
+      </h1>
+      <p
+        style={{
+          fontFamily: font,
+          fontSize: 16,
+          opacity: 0.7,
+          margin: 0,
+          lineHeight: 1.6,
+        }}
+      >
+        Components will be added here.
+      </p>
+    </div>
+  ),
+};

packages/design-system/src/foundation/color/color.stories.tsx

@@ -214,7 +214,7 @@ function SemanticSwatch({ name, value }: { name: string; value: string }) {
 }
 
 const meta = {
-  title: "Color",
+  title: "Foundations/Color",
 } satisfies Meta;
 
 export default meta;
@@ -228,17 +228,16 @@ export const Color: StoryObj = {
         display: "flex",
         flexDirection: "column",
         gap: 40,
-        maxWidth: 960,
       }}
     >
       <div>
         <h1
           style={{
             fontFamily: font,
-            fontSize: 32,
+            fontSize: 28,
             fontWeight: 600,
             color: DSColor.typography.primary,
-            margin: "0 0 6px",
+            margin: "0 0 8px",
             lineHeight: 1.4,
           }}
         >
@@ -247,8 +246,9 @@ export const Color: StoryObj = {
         <p
           style={{
             fontFamily: font,
-            fontSize: 17,
+            fontSize: 16,
             color: DSColor.typography.primary,
+            opacity: 0.7,
             margin: 0,
             lineHeight: 1.6,
           }}
@@ -262,10 +262,10 @@ export const Color: StoryObj = {
         <h2
           style={{
             fontFamily: font,
-            fontSize: 22,
+            fontSize: 20,
             fontWeight: 600,
             color: DSColor.typography.primary,
-            margin: 0,
+            margin: "0 0 16px",
           }}
         >
           Primitives
@@ -275,7 +275,7 @@ export const Color: StoryObj = {
             <h3
               style={{
                 fontFamily: font,
-                fontSize: 15,
+                fontSize: 14,
                 fontWeight: 600,
                 color: DSColor.typography.primary,
                 textTransform: "uppercase" as const,
@@ -312,10 +312,10 @@ export const Color: StoryObj = {
         <h2
           style={{
             fontFamily: font,
-            fontSize: 22,
+            fontSize: 20,
             fontWeight: 600,
             color: DSColor.typography.primary,
-            margin: 0,
+            margin: "0 0 16px",
           }}
         >
           Semantic
@@ -325,7 +325,7 @@ export const Color: StoryObj = {
             <h3
               style={{
                 fontFamily: font,
-                fontSize: 15,
+                fontSize: 14,
                 fontWeight: 600,
                 color: DSColor.typography.primary,
                 textTransform: "uppercase" as const,

packages/design-system/src/foundation/icon/icon.stories.tsx

@@ -10,7 +10,7 @@ const iconEntries = Object.entries(Icons).filter(
 ) as Array<[string, React.FC<Icons.DSIconProps>]>;
 
 const meta = {
-  title: "Icon",
+  title: "Foundations/Icon",
 } satisfies Meta;
 
 export default meta;
@@ -29,20 +29,24 @@ export const Icon: StoryObj = {
       <div>
         <h1
           style={{
-            fontSize: 32,
+            fontFamily: font,
+            fontSize: 28,
             fontWeight: 600,
             color: DSColor.typography.primary,
-            margin: "0 0 6px",
+            margin: "0 0 8px",
+            lineHeight: 1.4,
           }}
         >
           Icon
         </h1>
         <p
           style={{
-            fontSize: 17,
+            fontFamily: font,
+            fontSize: 16,
             color: DSColor.typography.primary,
             opacity: 0.7,
             margin: 0,
+            lineHeight: 1.6,
           }}
         >
           {iconEntries.length} icons synced from Figma. All icons accept{" "}

packages/design-system/src/foundation/typography/typography.stories.tsx

@@ -1,4 +1,11 @@
+import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
+import {
+  Title,
+  Description,
+  Primary,
+  Controls,
+} from "@storybook/addon-docs/blocks";
 import { DSTypography } from "./typography";
 import { DSColor } from "../color";
 import { dsTypographyTokens } from "./typography-tokens";
@@ -126,13 +133,78 @@ function TokenRow({ sizeKey }: { sizeKey: DSTypographyTokensKey }) {
 }
 
 const meta = {
-  title: "Typography",
-} satisfies Meta;
+  title: "Foundations/Typography",
+  component: DSTypography,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      page: () => (
+        <React.Fragment>
+          <Title />
+          <Description />
+          <Primary />
+          <h2 style={{ fontWeight: 600, marginTop: 32, marginBottom: 16 }}>
+            Props
+          </h2>
+          <Controls />
+        </React.Fragment>
+      ),
+    },
+  },
+  argTypes: {
+    size: {
+      control: "select",
+      options: Object.keys(dsTypographyTokens) as DSTypographyTokensKey[],
+      description: "Typography size token",
+    },
+    weight: {
+      control: "select",
+      options: ["semibold", "medium", "regular"],
+      description: "Font weight",
+    },
+    fontSize: {
+      control: "number",
+      description: "Override font size (px)",
+    },
+    color: {
+      control: "color",
+      description: "Text color — DSColor token or any CSS color",
+    },
+    as: {
+      control: "select",
+      options: ["span", "p", "h1", "h2", "h3", "h4", "div", "label"],
+      description: "HTML element to render as",
+    },
+  },
+} satisfies Meta<typeof DSTypography>;
 
 export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** @internal Docs preview — hidden from sidebar */
+export const _DocsPreview: Story = {
+  tags: ["!dev"],
+  parameters: {
+    docs: {
+      story: { inline: true },
+      canvas: { withToolbar: false, sourceState: "shown" },
+      source: {
+        code: `<DSTypography size="textMd" weight="medium" color={DSColor.typography.primary}>
+  The quick brown fox jumps over the lazy dog
+</DSTypography>`,
+      },
+    },
+  },
+  args: {
+    size: "textMd",
+    weight: "medium",
+    color: DSColor.typography.primary,
+    children: "The quick brown fox jumps over the lazy dog",
+  },
+};
 
-export const Typography: StoryObj = {
-  name: "Typography",
+/** Full showcase of all typography tokens */
+export const Showcase: Story = {
   render: () => (
     <div
       style={{
@@ -146,10 +218,10 @@ export const Typography: StoryObj = {
         <h1
           style={{
             fontFamily: font,
-            fontSize: 32,
+            fontSize: 28,
             fontWeight: 600,
             color: DSColor.typography.primary,
-            margin: "0 0 6px",
+            margin: "0 0 8px",
             lineHeight: 1.4,
           }}
         >
@@ -158,7 +230,7 @@ export const Typography: StoryObj = {
         <p
           style={{
             fontFamily: font,
-            fontSize: 17,
+            fontSize: 16,
             color: DSColor.typography.primary,
             opacity: 0.7,
             margin: 0,
@@ -173,7 +245,7 @@ export const Typography: StoryObj = {
         <h2
           style={{
             fontFamily: font,
-            fontSize: 22,
+            fontSize: 20,
             fontWeight: 600,
             color: DSColor.typography.primary,
             margin: "0 0 8px",
@@ -198,7 +270,7 @@ export const Typography: StoryObj = {
         <h2
           style={{
             fontFamily: font,
-            fontSize: 22,
+            fontSize: 20,
             fontWeight: 600,
             color: DSColor.typography.primary,
             margin: "0 0 16px",
@@ -250,3 +322,13 @@ export const Typography: StoryObj = {
     </div>
   ),
 };
+
+/** Interactive playground — use Controls to change props */
+export const Playground: Story = {
+  args: {
+    size: "textMd",
+    weight: "medium",
+    color: DSColor.typography.primary,
+    children: "The quick brown fox jumps over the lazy dog",
+  },
+};