mingle-website/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the official website for 밍글 스튜디오 (Mingle Studio), a motion capture studio located in Incheon, South Korea. The website is a multi-page static site built with vanilla HTML, CSS, and JavaScript, showcasing motion capture services, studio galleries, and client portfolios.

Tech Stack: Pure HTML5, CSS3 (with CSS Variables), Vanilla JavaScript (ES6+), no framework dependencies

Architecture & Structure

Page Architecture

The site follows a modular component-based structure:

• Main Pages: index.html, about.html, services.html, portfolio.html, gallery.html, contact.html, qna.html, 404.html
• Shared Components: components/header.html, components/footer.html
• Page-specific Assets: Each page has dedicated CSS (css/[page].css) and JavaScript (js/[page].js) files
• Common Assets: css/common.css and js/common.js provide shared functionality

Component Loading System

The site uses a dynamic component loading system implemented in js/common.js:

• Header and footer are loaded via fetch() API from components/ directory
• Fallback System: Pages should include a static backup footer in HTML that gets hidden when dynamic loading succeeds (check backupFooter logic in loadComponents())
• Components are initialized after DOM load with proper error handling
• Loading sequence: showPageLoading() → loadComponents() → initLazyLoading() → hidePageLoading()

CSS Architecture

• CSS Variables: Defined in :root of common.css with motion capture/VTuber orange theme
• Modular Approach: Common styles in common.css, page-specific styles in separate files
• Responsive Design: Mobile-first approach with breakpoints at 768px and 1200px
• Color Scheme: Primary orange (#ff8800) with gradient variations for modern tech aesthetic

Development Commands

Server Options

Node.js (권장):

npm run dev          # http://localhost:8000
npm start           # 같은 기능
npm run serve       # 같은 기능
npm test           # 도움말 + 서버 시작

Python (Alternative):

python server.py                # Custom server with auto-open on port 8001
python -m http.server 8000      # Basic Python server on port 8000

Note: The custom Python server (server.py) uses port 8001 and includes automatic port detection, browser opening, and clean URL support (.html extension optional).

Development Features

• Auto Browser Opening: Python server automatically opens http://localhost:8001 (or available port)
• Clean URLs: .html extension optional for access (e.g., /about works as /about.html)
• Dev Optimizations: Cache disabled, CORS headers added
• Port Auto-Detection: Python server finds available ports from 8001-8020 if default is occupied
• Error Handling: Port conflicts and basic error scenarios handled gracefully

Available URLs

When using npm scripts (port 8000):

• Homepage: http://localhost:8000/
• About: http://localhost:8000/about
• Services: http://localhost:8000/services
• Portfolio: http://localhost:8000/portfolio
• Gallery: http://localhost:8000/gallery
• Contact: http://localhost:8000/contact
• Q&A: http://localhost:8000/qna

When using python server.py (port 8001 or auto-detected):

• The server will display available URLs with the detected port

Key Technical Details

JavaScript Module System

• Common Utilities (js/common.js): Exports functions via window.commonUtils object for use in page-specific scripts
  • Navigation handling with hamburger menu
  • Notification system with 4 types (success, error, warning, info)
  • Lazy loading for YouTube iframes and images using IntersectionObserver
  • Loading state management (page-level and component-level)
  • Utility functions: debounce, throttle, isValidEmail
• Popup System (js/popup.js): Cookie-based "don't show today" functionality for main page popups

SEO Optimization

• Structured data (JSON-LD) with LocalBusiness schema for search engines
• Comprehensive meta tags including Open Graph, Twitter Cards, and Korean platform-specific tags
• Sitemap.xml without lastmod dates to prevent unwanted date display in search results
• Favicon system: Both ICO (mingle-logo.ico) and WebP (mingle-logo.webp) formats

Image Management

• Studio images stored in Studio_Image/ directory using WebP format for optimization
• Gallery system dynamically references these images with descriptive alt text
• Logo assets: mingle-logo.webp (primary) and mingle-logo.ico (favicon)

Form Handling & Interactivity

• Contact form with real-time validation in js/contact.js
• Lazy loading implementation for performance optimization
• Scroll animations and intersection observers for modern UX

Content Management

Adding Gallery Images

1. Add new WebP images to Studio_Image/ directory
2. Update gallery.html with new gallery items following the existing pattern:

   <div class="gallery-item">
       <img src="Studio_Image/[filename].webp" alt="descriptive text" class="gallery-img" loading="lazy">
       <div class="gallery-caption">Caption Text</div>
   </div>
   

Adding Portfolio Videos

• YouTube videos: Update portfolio.html with iframe embed using data-src for lazy loading
• SOOP/streaming VODs: Direct iframe source for broadcast examples

Navigation Updates

When adding new pages, update components/header.html navigation links and ensure corresponding CSS/JS files follow the naming convention (css/[page].css, js/[page].js).

Important Notes

File Structure Conventions

• Each page has three files: [page].html, css/[page].css, js/[page].js
• Backup files may exist (e.g., index_backup.html, index_new.html) - these are not actively used
• All pages must include placeholders for dynamic components:
  • <div id="header-placeholder"></div> for header
  • <div id="footer-placeholder"></div> for footer
• Page-specific CSS and JS are loaded after common files for proper override capability

Styling System

Access the orange motion capture theme via CSS variables defined in common.css:

--primary-color: #ff8800;
--gradient-main: linear-gradient(135deg, #ff8800 0%, #ff6600 100%);
--navbar-height: 70px;

Common Utilities Access

Page-specific scripts can access common functions via window.commonUtils:

// Show notification
window.commonUtils.showNotification('Message', 'success');

// Validate email
window.commonUtils.isValidEmail('test@example.com');

// Use debounce/throttle
const debouncedFn = window.commonUtils.debounce(myFn, 300);

Business Context

This website represents a motion capture studio business with:

• Primary Service: OptiTrack-based motion capture studio rental (22만원/hour)
• Target Market: VTubers, game developers, content creators
• Location: Incheon Techno Valley, unique positioning as Incheon's only motion capture facility
• Technical Specs: 28 OptiTrack cameras, 8×7m capture space

Understanding this context helps with content updates, SEO optimization, and feature development that aligns with the studio's business objectives.