[feat] Add Storybook setup and NodePreview story (#4861)

* [feat] Add Storybook setup and NodePreview story - Install and configure Storybook v9.1.1 for Vue 3 - Set up Storybook configuration with Vite integration - Add Pinia store support for Storybook environment - Create comprehensive NodePreview.stories.ts with multiple node examples: - KSampler node (complex node with multiple inputs/outputs) - CLIP Text Encode node (simple text input node) - VAE Decode node (image processing node) - Example with long markdown description - Configure project paths and aliases for Storybook - Stories demonstrate various ComfyUI node types with realistic mock data - Update tsconfig.eslint.json to include Storybook files - Fix ESLint issues with imports and number precision - Add Storybook ESLint plugin configuration 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * [feat] Improve Storybook configuration and setup - Add comprehensive PrimeVue theme setup with ComfyUI preset - Configure proper Vue app setup with Pinia stores, i18n, and services - Remove unused onboarding addon from Storybook dependencies - Improve Vite configuration with better chunking and alias resolution - Add proper CSS imports and styling for ComfyUI components 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * [docs] Add comprehensive Storybook documentation - Add README.md explaining Storybook usage, benefits, and comparison with other tools - Add CLAUDE.md with development guidelines for working with Storybook - Include best practices, troubleshooting tips, and integration notes - Address PR review feedback for better developer onboarding 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * [refactor] Remove ts-expect-error comment from Storybook preview 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * [bugfix] Fix TypeScript errors in Load3D components and GLTF test - Fix type mismatches in Load3DScene eventConfig by casting string values to proper enum types (MaterialMode, CameraType, UpDirection) - Fix Uint8Array vs ArrayBuffer type issues in GLTF test by using .buffer property - Remove unused @ts-expect-error comment in Rectangle.ts 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * [feat] Add Chromatic GitHub Action for Storybook visual testing - Add automated visual regression testing for Storybook components - Configure workflow to run on main branch and PRs - Auto-accept changes on main branch for baseline updates - Uses build-storybook script for optimized builds 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * [docs] Add Chromatic documentation to Storybook README - Document Chromatic visual testing integration - Add information about automated testing workflow - Include best practices for visual regression testing - Explain how to view and manage test results 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * chore(chromatic.yaml): restrict push branches to main only for better workflow management * [feat] Rebase branch onto main and update Storybook configuration - Rebase sno-storybook branch onto origin/main with latest changes - Update .storybook/main.ts with additional plugins and component configuration - Add icons and component resolvers for Storybook support - Update .gitignore with new entries - Regenerate package-lock.json after rebase conflicts 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * [bugfix] Fix TypeScript errors in SubgraphNode type checking Add proper type validation for subgraph node selection before calling SubgraphNode-specific methods. This prevents undefined values from being passed to functions expecting SubgraphNode parameters. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * fix(vite.config.mts): correct path alias for src directory to ensure proper resolution in the project refactor(vite.config.mts): adjust templates proxy configuration for better readability and maintainability * [feat] Remove bun.lock as it's now ignored * [bugfix] Fix Storybook builder require() error by converting main.ts to main.mjs - Convert .storybook/main.ts to main.mjs to resolve ES module compatibility - Use dynamic imports instead of static imports to avoid require() errors - Add .storybook directory to tsconfig.json includes - Storybook build and dev server now work correctly 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * chore(storybook): replace main.mjs with main.ts for improved type safety and maintainability fix(storybook): remove unused import map plugins in Storybook configuration to prevent potential issues fix(storybook): update color palette store initialization to streamline code and improve readability * [feat] Optimize Chromatic workflow with automated PR status comments - Replace complex GitHub Script actions with edumserrano/find-create-or-update-comment@v3 - Add comprehensive PR comments showing Storybook build progress and results - Include build metrics: components, stories, visual changes, and errors - Add direct links to Chromatic builds and Storybook previews - Reduce workflow complexity by ~60 lines while maintaining functionality - Use native GitHub Actions expressions for cleaner maintainability 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com> * chore(chromatic.yaml): move permissions section inside the chromatic-deployment job for better organization and clarity * [fix] Resolve Vite CJS deprecation warning in Storybook config - Use dynamic import for mergeConfig to avoid CJS build warning - Replace static import with dynamic import in viteFinal function - Maintain type safety with separate type import - Fixes "The CJS build of Vite's Node API is deprecated" warning 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * fix(chromatic.yaml): change edit-mode from replace to append to preserve existing comments in pull request * [fix] Replace __dirname with process.cwd() in Storybook config __dirname is not available in all environments. Using process.cwd() provides better compatibility and resolves path issues in Storybook. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * feature: storybook-setting (#5088) --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Jin Yi <jin12cc@gmail.com>
2026-01-26 19:09:52 +00:00 · 2025-08-19 11:05:28 +08:00
parent 727a3494e0
commit 451ef24ea6
19 changed files with 2459 additions and 608 deletions
--- a/.github/workflows/chromatic.yaml
+++ b/.github/workflows/chromatic.yaml
@@ -0,0 +1,96 @@
+name: 'Chromatic'
+
+# - [Automate Chromatic with GitHub Actions • Chromatic docs]( https://www.chromatic.com/docs/github-actions/ )
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  chromatic-deployment:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      issues: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required for Chromatic baseline
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Get current time
+        id: current-time
+        run: echo "time=$(date -u '+%m/%d/%Y, %I:%M:%S %p')" >> $GITHUB_OUTPUT
+
+      - name: Comment PR - Build Started
+        if: github.event_name == 'pull_request'
+        uses: edumserrano/find-create-or-update-comment@v3
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          body-includes: '<!-- STORYBOOK_BUILD_STATUS -->'
+          comment-author: 'github-actions[bot]'
+          edit-mode: append
+          body: |
+            <!-- STORYBOOK_BUILD_STATUS -->
+            ## 🎨 Storybook Build Status
+
+            🔄 **Building Storybook and running visual tests...**
+
+            ⏳ Build started at: ${{ steps.current-time.outputs.time }} UTC
+
+            ---
+            *This comment will be updated when the build completes*
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build Storybook and run Chromatic
+        id: chromatic
+        uses: chromaui/action@latest
+        with:
+          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+          buildScriptName: build-storybook
+          autoAcceptChanges: 'main' # Auto-accept changes on main branch
+          exitOnceUploaded: true # Don't wait for UI tests to complete
+
+      - name: Get completion time
+        id: completion-time
+        if: always()
+        run: echo "time=$(date -u '+%m/%d/%Y, %I:%M:%S %p')" >> $GITHUB_OUTPUT
+
+      - name: Comment PR - Build Complete
+        if: github.event_name == 'pull_request' && always()
+        uses: edumserrano/find-create-or-update-comment@v3
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          body-includes: '<!-- STORYBOOK_BUILD_STATUS -->'
+          comment-author: 'github-actions[bot]'
+          edit-mode: replace
+          body: |
+            <!-- STORYBOOK_BUILD_STATUS -->
+            ## 🎨 Storybook Build Status
+
+            ${{ steps.chromatic.outcome == 'success' && '✅' || '❌' }} **${{ steps.chromatic.outcome == 'success' && 'Build completed successfully!' || 'Build failed!' }}**
+
+            ⏰ Completed at: ${{ steps.completion-time.outputs.time }} UTC
+
+            ### 📊 Build Summary
+            - **Components**: ${{ steps.chromatic.outputs.componentCount || '0' }}
+            - **Stories**: ${{ steps.chromatic.outputs.testCount || '0' }}
+            - **Visual changes**: ${{ steps.chromatic.outputs.changeCount || '0' }}
+            - **Errors**: ${{ steps.chromatic.outputs.errorCount || '0' }}
+
+            ### 🔗 Links
+            ${{ steps.chromatic.outputs.buildUrl && format('- [📸 View Chromatic Build]({0})', steps.chromatic.outputs.buildUrl) || '' }}
+            ${{ steps.chromatic.outputs.storybookUrl && format('- [📖 Preview Storybook]({0})', steps.chromatic.outputs.storybookUrl) || '' }}
+
+            ---
+            ${{ steps.chromatic.outcome == 'success' && '🎉 Your Storybook is ready for review!' || '⚠️ Please check the workflow logs for error details.' }}
--- a/.gitignore
+++ b/.gitignore
@@ -72,3 +72,7 @@ vite.config.mts.timestamp-*.mjs

 # Linux core dumps
 ./core
+
+*storybook.log
+storybook-static
+
--- a/.storybook/CLAUDE.md
+++ b/.storybook/CLAUDE.md
@@ -0,0 +1,197 @@
+# Storybook Development Guidelines for Claude
+
+## Quick Commands
+
+- `npm run storybook`: Start Storybook development server
+- `npm run build-storybook`: Build static Storybook
+- `npm run test:component`: Run component tests (includes Storybook components)
+
+## Development Workflow for Storybook
+
+1. **Creating New Stories**:
+   - Place `*.stories.ts` files alongside components
+   - Follow the naming pattern: `ComponentName.stories.ts`
+   - Use realistic mock data that matches ComfyUI schemas
+
+2. **Testing Stories**:
+   - Verify stories render correctly in Storybook UI
+   - Test different component states and edge cases
+   - Ensure proper theming and styling
+
+3. **Code Quality**:
+   - Run `npm run typecheck` to verify TypeScript
+   - Run `npm run lint` to check for linting issues
+   - Follow existing story patterns and conventions
+
+## Story Creation Guidelines
+
+### Basic Story Structure
+
+```typescript
+import type { Meta, StoryObj } from '@storybook/vue3'
+import ComponentName from './ComponentName.vue'
+
+const meta: Meta<typeof ComponentName> = {
+  title: 'Category/ComponentName',
+  component: ComponentName,
+  parameters: {
+    layout: 'centered' // or 'fullscreen', 'padded'
+  }
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    // Component props
+  }
+}
+```
+
+### Mock Data Patterns
+
+For ComfyUI components, use realistic mock data:
+
+```typescript
+// Node definition mock
+const mockNodeDef = {
+  input: {
+    required: {
+      prompt: ["STRING", { multiline: true }]
+    }
+  },
+  output: ["CONDITIONING"],
+  output_is_list: [false],
+  category: "conditioning"
+}
+
+// Component instance mock
+const mockComponent = {
+  id: "1",
+  type: "CLIPTextEncode",
+  // ... other properties
+}
+```
+
+### Common Story Variants
+
+Always include these story variants when applicable:
+
+- **Default**: Basic component with minimal props
+- **WithData**: Component with realistic data
+- **Loading**: Component in loading state
+- **Error**: Component with error state
+- **LongContent**: Component with edge case content
+- **Empty**: Component with no data
+
+### Storybook-Specific Code Patterns
+
+#### Store Access
+```typescript
+// In stories, access stores through the setup function
+export const WithStore: Story = {
+  render: () => ({
+    setup() {
+      const store = useMyStore()
+      return { store }
+    },
+    template: '<MyComponent :data="store.data" />'
+  })
+}
+```
+
+#### Event Testing
+```typescript
+export const WithEvents: Story = {
+  args: {
+    onUpdate: fn() // Use Storybook's fn() for action logging
+  }
+}
+```
+
+## Configuration Notes
+
+### Vue App Setup
+The Storybook preview is configured with:
+- Pinia stores initialized
+- PrimeVue with ComfyUI theme
+- i18n internationalization
+- All necessary CSS imports
+
+### Build Configuration
+- Vite integration with proper alias resolution
+- Manual chunking for better performance
+- TypeScript support with strict checking
+- CSS processing for Vue components
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Import Errors**: Verify `@/` alias is working correctly
+2. **Missing Styles**: Ensure CSS imports are in `preview.ts`
+3. **Store Errors**: Check store initialization in setup
+4. **Type Errors**: Use proper TypeScript types for story args
+
+### Debug Commands
+
+```bash
+# Check TypeScript issues
+npm run typecheck
+
+# Lint Storybook files
+npm run lint .storybook/
+
+# Build to check for production issues
+npm run build-storybook
+```
+
+## File Organization
+
+```
+.storybook/
+├── main.ts          # Core configuration
+├── preview.ts       # Global setup and decorators
+├── README.md        # User documentation
+└── CLAUDE.md        # This file - Claude guidelines
+
+src/
+├── components/
+│   └── MyComponent/
+│       ├── MyComponent.vue
+│       └── MyComponent.stories.ts
+```
+
+## Integration with ComfyUI
+
+### Available Context
+
+Stories have access to:
+- All ComfyUI stores (widgetStore, colorPaletteStore, etc.)
+- PrimeVue components with ComfyUI theming
+- Internationalization system
+- ComfyUI CSS variables and styling
+
+### Testing Components
+
+When testing ComfyUI-specific components:
+1. Use realistic node definitions and data structures
+2. Test with different node types (sampling, conditioning, etc.)
+3. Verify proper CSS theming and dark/light modes
+4. Check component behavior with various input combinations
+
+### Performance Considerations
+
+- Use manual chunking for large dependencies
+- Minimize bundle size by avoiding unnecessary imports
+- Leverage Storybook's lazy loading capabilities
+- Profile build times and optimize as needed
+
+## Best Practices
+
+1. **Keep Stories Focused**: Each story should demonstrate one specific use case
+2. **Use Descriptive Names**: Story names should clearly indicate what they show
+3. **Document Complex Props**: Use JSDoc comments for complex prop types
+4. **Test Edge Cases**: Create stories for unusual but valid use cases
+5. **Maintain Consistency**: Follow established patterns in existing stories
--- a/.storybook/README.md
+++ b/.storybook/README.md
@@ -0,0 +1,173 @@
+# Storybook Configuration for ComfyUI Frontend
+
+## What is Storybook?
+
+Storybook is a frontend workshop for building UI components and pages in isolation. It allows developers to:
+
+- Build components independently from the main application
+- Test components with different props and states
+- Document component APIs and usage patterns
+- Share components across teams and projects
+- Catch visual regressions through visual testing
+
+## Storybook vs Other Testing Tools
+
+| Tool | Purpose | Use Case |
+|------|---------|----------|
+| **Storybook** | Component isolation & documentation | Developing, testing, and showcasing individual UI components |
+| **Playwright** | End-to-end testing | Full user workflow testing across multiple pages |
+| **Vitest** | Unit testing | Testing business logic, utilities, and component behavior |
+| **Vue Testing Library** | Component testing | Testing component interactions and DOM output |
+
+### When to Use Storybook
+
+**✅ Use Storybook for:**
+- Developing new UI components in isolation
+- Creating component documentation and examples
+- Testing different component states and props
+- Sharing components with designers and stakeholders
+- Visual regression testing
+- Building a component library or design system
+
+**❌ Don't use Storybook for:**
+- Testing complex user workflows (use Playwright)
+- Testing business logic (use Vitest)
+- Integration testing between components (use Vue Testing Library)
+
+## How to Use Storybook
+
+### Development Commands
+
+```bash
+# Start Storybook development server
+npm run storybook
+
+# Build static Storybook for deployment
+npm run build-storybook
+```
+
+### Creating Stories
+
+Stories are located alongside components in `src/` directories with the pattern `*.stories.ts`:
+
+```typescript
+// MyComponent.stories.ts
+import type { Meta, StoryObj } from '@storybook/vue3'
+import MyComponent from './MyComponent.vue'
+
+const meta: Meta<typeof MyComponent> = {
+  title: 'Components/MyComponent',
+  component: MyComponent,
+  parameters: {
+    layout: 'centered'
+  }
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    title: 'Hello World'
+  }
+}
+
+export const WithVariant: Story = {
+  args: {
+    title: 'Variant Example',
+    variant: 'secondary'
+  }
+}
+```
+
+### Available Features
+
+- **Vue 3 Support**: Full Vue 3 composition API and reactivity
+- **PrimeVue Integration**: All PrimeVue components and theming
+- **ComfyUI Theming**: Custom ComfyUI theme preset applied
+- **Pinia Stores**: Access to application stores for components that need state
+- **TypeScript**: Full TypeScript support with proper type checking
+- **CSS/SCSS**: Component styling support
+- **Auto-documentation**: Automatic prop tables and component documentation
+- **Chromatic Integration**: Automated visual regression testing for component stories
+
+## Development Tips
+
+### Best Practices
+
+1. **Keep Stories Simple**: Each story should demonstrate one specific use case
+2. **Use Realistic Data**: Use data that resembles real application usage
+3. **Document Edge Cases**: Create stories for loading states, errors, and edge cases
+4. **Group Related Stories**: Use consistent naming and grouping for related components
+
+### Component Testing Strategy
+
+```typescript
+// Example: Testing different component states
+export const Loading: Story = {
+  args: {
+    isLoading: true
+  }
+}
+
+export const Error: Story = {
+  args: {
+    error: 'Failed to load data'
+  }
+}
+
+export const WithLongText: Story = {
+  args: {
+    description: 'Very long description that might cause layout issues...'
+  }
+}
+```
+
+### Debugging Tips
+
+- Use browser DevTools to inspect component behavior
+- Check the Storybook console for Vue warnings or errors
+- Use the Controls addon to dynamically change props
+- Leverage the Actions addon to test event handling
+
+## Configuration Files
+
+- **`main.ts`**: Core Storybook configuration and Vite integration
+- **`preview.ts`**: Global decorators, parameters, and Vue app setup
+- **`manager.ts`**: Storybook UI customization (if needed)
+
+## Chromatic Visual Testing
+
+This project uses [Chromatic](https://chromatic.com) for automated visual regression testing of Storybook components.
+
+### How It Works
+
+- **Automated Testing**: Every push to `main` and `sno-storybook` branches triggers Chromatic builds
+- **Pull Request Reviews**: PRs against `main` branch include visual diffs for component changes
+- **Baseline Management**: Changes on `main` branch are automatically accepted as new baselines
+- **Cross-browser Testing**: Tests across multiple browsers and viewports
+
+### Viewing Results
+
+1. Check the GitHub Actions tab for Chromatic workflow status
+2. Click on the Chromatic build link in PR comments to review visual changes
+3. Accept or reject visual changes directly in the Chromatic UI
+
+### Best Practices for Visual Testing
+
+- **Consistent Stories**: Ensure stories render consistently across different environments
+- **Meaningful Names**: Use descriptive story names that clearly indicate the component state
+- **Edge Cases**: Include stories for loading, error, and empty states
+- **Realistic Data**: Use data that closely resembles production usage
+
+## Integration with ComfyUI
+
+This Storybook setup includes:
+
+- ComfyUI-specific theming and styling
+- Pre-configured Pinia stores for state management
+- Internationalization (i18n) support
+- PrimeVue component library integration
+- Proper alias resolution for `@/` imports
+
+For component-specific examples, see the NodePreview stories in `src/components/node/`.
--- a/.storybook/main.ts
+++ b/.storybook/main.ts
@@ -0,0 +1,96 @@
+import type { StorybookConfig } from '@storybook/vue3-vite'
+import { FileSystemIconLoader } from 'unplugin-icons/loaders'
+import IconsResolver from 'unplugin-icons/resolver'
+import Icons from 'unplugin-icons/vite'
+import Components from 'unplugin-vue-components/vite'
+import type { InlineConfig } from 'vite'
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  addons: ['@storybook/addon-docs'],
+  framework: {
+    name: '@storybook/vue3-vite',
+    options: {}
+  },
+  async viteFinal(config) {
+    // Use dynamic import to avoid CJS deprecation warning
+    const { mergeConfig } = await import('vite')
+
+    // Filter out any plugins that might generate import maps
+    if (config.plugins) {
+      config.plugins = config.plugins.filter((plugin: any) => {
+        if (plugin && plugin.name && plugin.name.includes('import-map')) {
+          return false
+        }
+        return true
+      })
+    }
+
+    return mergeConfig(config, {
+      // Replace plugins entirely to avoid inheritance issues
+      plugins: [
+        // Only include plugins we explicitly need for Storybook
+        Icons({
+          compiler: 'vue3',
+          customCollections: {
+            comfy: FileSystemIconLoader(
+              process.cwd() + '/src/assets/icons/custom'
+            )
+          }
+        }),
+        Components({
+          dts: false, // Disable dts generation in Storybook
+          resolvers: [
+            IconsResolver({
+              customCollections: ['comfy']
+            })
+          ],
+          dirs: [
+            process.cwd() + '/src/components',
+            process.cwd() + '/src/layout',
+            process.cwd() + '/src/views'
+          ],
+          deep: true,
+          extensions: ['vue']
+        })
+        // Note: Explicitly NOT including generateImportMapPlugin to avoid externalization
+      ],
+      server: {
+        allowedHosts: true
+      },
+      resolve: {
+        alias: {
+          '@': process.cwd() + '/src'
+        }
+      },
+      build: {
+        rollupOptions: {
+          external: () => {
+            // Don't externalize any modules in Storybook build
+            // This ensures PrimeVue and other dependencies are bundled
+            return false
+          },
+          onwarn: (warning, warn) => {
+            // Suppress specific warnings
+            if (
+              warning.code === 'UNUSED_EXTERNAL_IMPORT' &&
+              warning.message?.includes('resolveComponent')
+            ) {
+              return
+            }
+            // Suppress Storybook font asset warnings
+            if (
+              warning.code === 'UNRESOLVED_IMPORT' &&
+              warning.message?.includes('nunito-sans')
+            ) {
+              return
+            }
+            warn(warning)
+          }
+        },
+        chunkSizeWarningLimit: 1000
+      }
+    } satisfies InlineConfig)
+  }
+}
+export default config
--- a/.storybook/preview-head.html
+++ b/.storybook/preview-head.html
@@ -0,0 +1,34 @@
+<style>
+  body {
+    overflow-y: auto !important;
+    transition: background-color 0.3s ease, color 0.3s ease;
+  }
+
+  /* Light theme default */
+  body {
+    background-color: #ffffff;
+    color: #1a1a1a;
+  }
+
+  /* Dark theme styles */
+  body.dark-theme,
+  .dark-theme body {
+    background-color: #0a0a0a;
+    color: #e5e5e5;
+  }
+
+  /* Ensure Storybook canvas follows theme */
+  .sb-show-main {
+    transition: background-color 0.3s ease;
+  }
+
+  .dark-theme .sb-show-main,
+  .dark-theme .docs-story {
+    background-color: #0a0a0a !important;
+  }
+
+  /* Fix for Storybook controls panel in dark mode */
+  .dark-theme .docblock-argstable-body {
+    color: #e5e5e5;
+  }
+</style>
--- a/.storybook/preview.ts
+++ b/.storybook/preview.ts
@@ -0,0 +1,104 @@
+import { definePreset } from '@primevue/themes'
+import Aura from '@primevue/themes/aura'
+import { setup } from '@storybook/vue3'
+import type { Preview } from '@storybook/vue3-vite'
+import { createPinia } from 'pinia'
+import 'primeicons/primeicons.css'
+import PrimeVue from 'primevue/config'
+import ConfirmationService from 'primevue/confirmationservice'
+import ToastService from 'primevue/toastservice'
+import Tooltip from 'primevue/tooltip'
+
+import '../src/assets/css/style.css'
+import { i18n } from '../src/i18n'
+import '../src/lib/litegraph/public/css/litegraph.css'
+import { useWidgetStore } from '../src/stores/widgetStore'
+import { useColorPaletteStore } from '../src/stores/workspace/colorPaletteStore'
+
+const ComfyUIPreset = definePreset(Aura, {
+  semantic: {
+    // @ts-expect-error fix me
+    primary: Aura['primitive'].blue
+  }
+})
+
+// Setup Vue app for Storybook
+setup((app) => {
+  app.directive('tooltip', Tooltip)
+  const pinia = createPinia()
+  app.use(pinia)
+
+  // Initialize stores
+  useColorPaletteStore(pinia)
+  useWidgetStore(pinia)
+
+  app.use(i18n)
+  app.use(PrimeVue, {
+    theme: {
+      preset: ComfyUIPreset,
+      options: {
+        prefix: 'p',
+        cssLayer: {
+          name: 'primevue',
+          order: 'primevue, tailwind-utilities'
+        },
+        darkModeSelector: '.dark-theme, :root:has(.dark-theme)'
+      }
+    }
+  })
+  app.use(ConfirmationService)
+  app.use(ToastService)
+})
+
+// Dark theme decorator
+export const withTheme = (Story: any, context: any) => {
+  const theme = context.globals.theme || 'light'
+
+  // Apply theme class to document root
+  if (theme === 'dark') {
+    document.documentElement.classList.add('dark-theme')
+    document.body.classList.add('dark-theme')
+  } else {
+    document.documentElement.classList.remove('dark-theme')
+    document.body.classList.remove('dark-theme')
+  }
+
+  return Story()
+}
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i
+      }
+    },
+    backgrounds: {
+      default: 'light',
+      values: [
+        { name: 'light', value: '#ffffff' },
+        { name: 'dark', value: '#0a0a0a' }
+      ]
+    }
+  },
+  globalTypes: {
+    theme: {
+      name: 'Theme',
+      description: 'Global theme for components',
+      defaultValue: 'light',
+      toolbar: {
+        icon: 'circlehollow',
+        items: [
+          { value: 'light', icon: 'sun', title: 'Light' },
+          { value: 'dark', icon: 'moon', title: 'Dark' }
+        ],
+        showName: true,
+        dynamicTitle: true
+      }
+    }
+  },
+  decorators: [withTheme]
+}
+
+export default preview
--- a/README.md
+++ b/README.md
@@ -529,6 +529,10 @@ For detailed development setup, testing procedures, and technical information, p

 See [locales/README.md](src/locales/README.md) for details.

+### Storybook
+
+See [.storybook/README.md](.storybook/README.md) for component development and visual testing documentation.
+
 ## Troubleshooting

 For comprehensive troubleshooting and technical support, please refer to our official documentation:
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -1,6 +1,8 @@
+// For more info, see https://github.com/storybookjs/eslint-plugin-storybook#configuration-flat-config-format
 import pluginJs from '@eslint/js'
 import pluginI18n from '@intlify/eslint-plugin-vue-i18n'
 import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'
+import storybook from 'eslint-plugin-storybook'
 import unusedImports from 'eslint-plugin-unused-imports'
 import pluginVue from 'eslint-plugin-vue'
 import globals from 'globals'
@@ -94,5 +96,6 @@ export default [
        }
      ]
    }
-  }
+  },
+  ...storybook.configs['flat/recommended']
 ]
--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@@ -28,7 +28,9 @@
    "knip": "knip",
    "locale": "lobe-i18n locale",
    "collect-i18n": "playwright test --config=playwright.i18n.config.ts",
-    "json-schema": "tsx scripts/generate-json-schema.ts"
+    "json-schema": "tsx scripts/generate-json-schema.ts",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
  },
  "devDependencies": {
    "@eslint/js": "^9.8.0",
@@ -38,6 +40,8 @@
    "@lobehub/i18n-cli": "^1.20.0",
    "@pinia/testing": "^0.1.5",
    "@playwright/test": "^1.52.0",
+    "@storybook/addon-docs": "^9.1.1",
+    "@storybook/vue3-vite": "^9.1.1",
    "@trivago/prettier-plugin-sort-imports": "^5.2.0",
    "@types/dompurify": "^3.0.5",
    "@types/fs-extra": "^11.0.4",
@@ -51,6 +55,7 @@
    "eslint": "^9.12.0",
    "eslint-config-prettier": "^10.1.2",
    "eslint-plugin-prettier": "^5.2.6",
+    "eslint-plugin-storybook": "^9.1.1",
    "eslint-plugin-unused-imports": "^4.1.4",
    "eslint-plugin-vue": "^9.27.0",
    "fs-extra": "^11.2.0",
@@ -62,6 +67,7 @@
    "lint-staged": "^15.2.7",
    "postcss": "^8.4.39",
    "prettier": "^3.3.2",
+    "storybook": "^9.1.1",
    "tailwindcss": "^3.4.4",
    "tsx": "^4.15.6",
    "typescript": "^5.4.5",
--- a/src/components/load3d/Load3DAnimationScene.vue
+++ b/src/components/load3d/Load3DAnimationScene.vue
@@ -149,14 +149,14 @@ watch(

 const emit = defineEmits<{
  (e: 'animationListChange', animationList: string): void
-  (e: 'materialModeChange', materialMode: string): void
+  (e: 'materialModeChange', materialMode: MaterialMode): void
  (e: 'backgroundColorChange', color: string): void
  (e: 'lightIntensityChange', lightIntensity: number): void
  (e: 'fovChange', fov: number): void
-  (e: 'cameraTypeChange', cameraType: string): void
+  (e: 'cameraTypeChange', cameraType: CameraType): void
  (e: 'showGridChange', showGrid: boolean): void
  (e: 'showPreviewChange', showPreview: boolean): void
-  (e: 'upDirectionChange', direction: string): void
+  (e: 'upDirectionChange', direction: UpDirection): void
  (e: 'recording-status-change', status: boolean): void
 }>()

--- a/src/components/load3d/Load3DScene.vue
+++ b/src/components/load3d/Load3DScene.vue
@@ -42,12 +42,14 @@ const load3d = ref<Load3d | Load3dAnimation | null>(null)
 const loadingOverlayRef = ref<InstanceType<typeof LoadingOverlay> | null>(null)

 const eventConfig = {
-  materialModeChange: (value: string) => emit('materialModeChange', value),
+  materialModeChange: (value: string) =>
+    emit('materialModeChange', value as MaterialMode),
  backgroundColorChange: (value: string) =>
    emit('backgroundColorChange', value),
  lightIntensityChange: (value: number) => emit('lightIntensityChange', value),
  fovChange: (value: number) => emit('fovChange', value),
-  cameraTypeChange: (value: string) => emit('cameraTypeChange', value),
+  cameraTypeChange: (value: string) =>
+    emit('cameraTypeChange', value as CameraType),
  showGridChange: (value: boolean) => emit('showGridChange', value),
  showPreviewChange: (value: boolean) => emit('showPreviewChange', value),
  backgroundImageChange: (value: string) =>
@@ -55,7 +57,8 @@ const eventConfig = {
  backgroundImageLoadingStart: () =>
    loadingOverlayRef.value?.startLoading(t('load3d.loadingBackgroundImage')),
  backgroundImageLoadingEnd: () => loadingOverlayRef.value?.endLoading(),
-  upDirectionChange: (value: string) => emit('upDirectionChange', value),
+  upDirectionChange: (value: string) =>
+    emit('upDirectionChange', value as UpDirection),
  edgeThresholdChange: (value: number) => emit('edgeThresholdChange', value),
  modelLoadingStart: () =>
    loadingOverlayRef.value?.startLoading(t('load3d.loadingModel')),
@@ -184,15 +187,15 @@ watch(
 )

 const emit = defineEmits<{
-  (e: 'materialModeChange', materialMode: string): void
+  (e: 'materialModeChange', materialMode: MaterialMode): void
  (e: 'backgroundColorChange', color: string): void
  (e: 'lightIntensityChange', lightIntensity: number): void
  (e: 'fovChange', fov: number): void
-  (e: 'cameraTypeChange', cameraType: string): void
+  (e: 'cameraTypeChange', cameraType: CameraType): void
  (e: 'showGridChange', showGrid: boolean): void
  (e: 'showPreviewChange', showPreview: boolean): void
  (e: 'backgroundImageChange', backgroundImage: string): void
-  (e: 'upDirectionChange', upDirection: string): void
+  (e: 'upDirectionChange', upDirection: UpDirection): void
  (e: 'edgeThresholdChange', threshold: number): void
  (e: 'recordingStatusChange', status: boolean): void
 }>()
--- a/src/components/node/NodePreview.stories.ts
+++ b/src/components/node/NodePreview.stories.ts
@@ -0,0 +1,261 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+
+import type { ComfyNodeDef as ComfyNodeDefV2 } from '@/schemas/nodeDef/nodeDefSchemaV2'
+
+import NodePreview from './NodePreview.vue'
+
+// Mock node definition data for a typical ComfyUI node
+const mockNodeDef: ComfyNodeDefV2 = {
+  name: 'KSampler',
+  display_name: 'KSampler',
+  description:
+    'The main sampler node for generating images. Controls the denoising process using various samplers and schedulers.',
+  category: 'sampling',
+  output_node: false,
+  python_module: 'nodes',
+  inputs: {
+    model: {
+      type: 'MODEL',
+      name: 'model',
+      isOptional: false
+    },
+    positive: {
+      type: 'CONDITIONING',
+      name: 'positive',
+      isOptional: false
+    },
+    negative: {
+      type: 'CONDITIONING',
+      name: 'negative',
+      isOptional: false
+    },
+    latent_image: {
+      type: 'LATENT',
+      name: 'latent_image',
+      isOptional: false
+    },
+    seed: {
+      type: 'INT',
+      name: 'seed',
+      default: 0,
+      min: 0,
+      max: Number.MAX_SAFE_INTEGER,
+      isOptional: false
+    },
+    steps: {
+      type: 'INT',
+      name: 'steps',
+      default: 20,
+      min: 1,
+      max: 10000,
+      isOptional: false
+    },
+    cfg: {
+      type: 'FLOAT',
+      name: 'cfg',
+      default: 8.0,
+      min: 0.0,
+      max: 100.0,
+      step: 0.1,
+      isOptional: false
+    },
+    sampler_name: {
+      type: 'COMBO',
+      name: 'sampler_name',
+      options: [
+        'euler',
+        'euler_ancestral',
+        'heun',
+        'dpm_2',
+        'dpm_2_ancestral',
+        'lms',
+        'dpm_fast',
+        'dpm_adaptive',
+        'dpmpp_2s_ancestral',
+        'dpmpp_sde',
+        'dpmpp_2m'
+      ],
+      default: 'euler',
+      isOptional: false
+    },
+    scheduler: {
+      type: 'COMBO',
+      name: 'scheduler',
+      options: [
+        'normal',
+        'karras',
+        'exponential',
+        'sgm_uniform',
+        'simple',
+        'ddim_uniform'
+      ],
+      default: 'normal',
+      isOptional: false
+    },
+    denoise: {
+      type: 'FLOAT',
+      name: 'denoise',
+      default: 1.0,
+      min: 0.0,
+      max: 1.0,
+      step: 0.01,
+      isOptional: false
+    }
+  },
+  outputs: [
+    {
+      index: 0,
+      name: 'LATENT',
+      type: 'LATENT',
+      is_list: false
+    }
+  ]
+}
+
+// Simpler text node for comparison
+const mockTextNodeDef: ComfyNodeDefV2 = {
+  name: 'CLIPTextEncode',
+  display_name: 'CLIP Text Encode',
+  description:
+    'Encode text using CLIP to create conditioning for image generation.',
+  category: 'conditioning',
+  output_node: false,
+  python_module: 'nodes',
+  inputs: {
+    clip: {
+      type: 'CLIP',
+      name: 'clip',
+      isOptional: false
+    },
+    text: {
+      type: 'STRING',
+      name: 'text',
+      multiline: true,
+      default: '',
+      isOptional: false
+    }
+  },
+  outputs: [
+    {
+      index: 0,
+      name: 'CONDITIONING',
+      type: 'CONDITIONING',
+      is_list: false
+    }
+  ]
+}
+
+// Image processing node with multiple outputs
+const mockImageNodeDef: ComfyNodeDefV2 = {
+  name: 'VAEDecode',
+  display_name: 'VAE Decode',
+  description:
+    'Decode latent representation back to image using a Variational Autoencoder.',
+  category: 'latent',
+  output_node: false,
+  python_module: 'nodes',
+  inputs: {
+    samples: {
+      type: 'LATENT',
+      name: 'samples',
+      isOptional: false
+    },
+    vae: {
+      type: 'VAE',
+      name: 'vae',
+      isOptional: false
+    }
+  },
+  outputs: [
+    {
+      index: 0,
+      name: 'IMAGE',
+      type: 'IMAGE',
+      is_list: false
+    }
+  ]
+}
+
+const meta: Meta<typeof NodePreview> = {
+  title: 'Components/Node/NodePreview',
+  component: NodePreview,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'NodePreview displays a preview of a ComfyUI node with its inputs, outputs, and parameters. This component is used to show node information in sidebars and tooltips.'
+      }
+    }
+  },
+  argTypes: {
+    nodeDef: {
+      description: 'Node definition object containing all node metadata',
+      control: { type: 'object' }
+    }
+  },
+  tags: ['autodocs']
+}
+
+export default meta
+type Story = StoryObj<typeof NodePreview>
+
+export const KSamplerNode: Story = {
+  args: {
+    nodeDef: mockNodeDef
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'KSampler node - the main sampling node with multiple inputs including model, conditioning, and sampling parameters.'
+      }
+    }
+  }
+}
+
+export const TextEncodeNode: Story = {
+  args: {
+    nodeDef: mockTextNodeDef
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'CLIP Text Encode node - simple text input node for creating conditioning.'
+      }
+    }
+  }
+}
+
+export const ImageProcessingNode: Story = {
+  args: {
+    nodeDef: mockImageNodeDef
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'VAE Decode node - converts latent representation back to images.'
+      }
+    }
+  }
+}
+
+export const WithLongDescription: Story = {
+  args: {
+    nodeDef: {
+      ...mockNodeDef,
+      description:
+        'This is an example of a node with a very long description that should wrap properly and display in the description area below the node preview. It demonstrates how the component handles extensive documentation text and formatting. The description supports **markdown** formatting including *italics* and other styling elements.'
+    }
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Node preview with a longer, markdown-formatted description to test text wrapping and styling.'
+      }
+    }
+  }
+}
--- a/src/composables/useCoreCommands.ts
+++ b/src/composables/useCoreCommands.ts
@@ -10,7 +10,8 @@ import {
  LGraphEventMode,
  LGraphGroup,
  LGraphNode,
-  LiteGraph
+  LiteGraph,
+  SubgraphNode
 } from '@/lib/litegraph/src/litegraph'
 import { Point } from '@/lib/litegraph/src/litegraph'
 import { api } from '@/scripts/api'
@@ -823,6 +824,7 @@ export function useCoreCommands(): ComfyCommand[] {
        if (!graph) throw new TypeError('Canvas has no graph or subgraph set.')

        const subgraphNode = app.canvas.selectedItems.values().next().value
+        if (!(subgraphNode instanceof SubgraphNode)) return
        useNodeOutputStore().revokeSubgraphPreviews(subgraphNode)
        graph.unpackSubgraph(subgraphNode)
      }
--- a/src/lib/litegraph/src/infrastructure/Rectangle.ts
+++ b/src/lib/litegraph/src/infrastructure/Rectangle.ts
@@ -68,7 +68,6 @@ export class Rectangle extends Float64Array {
  override subarray(
    begin: number = 0,
    end?: number
-    // @ts-expect-error TypeScript lib typing issue - Float64Array is not generic
  ): Float64Array<ArrayBuffer> {
    const byteOffset = begin << 3
    const length = end === undefined ? end : end - begin
--- a/tests-ui/tests/scripts/metadata/gltf.test.ts
+++ b/tests-ui/tests/scripts/metadata/gltf.test.ts
@@ -50,9 +50,9 @@ describe('GLTF binary metadata parser', () => {
    const jsonData = jsonToBinary(jsonContent)
    const { header, headerView } = createGLTFFileStructure()

-    setHeaders(headerView, jsonData)
+    setHeaders(headerView, jsonData.buffer)

-    const chunkHeader = createJSONChunk(jsonData)
+    const chunkHeader = createJSONChunk(jsonData.buffer)

    const fileContent = new Uint8Array(
      header.byteLength + chunkHeader.byteLength + jsonData.byteLength
--- a/tsconfig.eslint.json
+++ b/tsconfig.eslint.json
@@ -15,6 +15,7 @@
    "browser_tests/**/*.ts",
    "scripts/**/*.js",
    "scripts/**/*.ts",
-    "tests-ui/**/*.ts"
+    "tests-ui/**/*.ts",
+    ".storybook/**/*.ts"
  ]
 }
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -37,6 +37,7 @@
    "src/types/**/*.d.ts",
    "tests-ui/**/*",
    "global.d.ts",
-    "vite.config.mts"
+    "vite.config.mts",
+    ".storybook/**/*"
  ]
 }