Technical Specification: Harmonic Comb Expansion Utility

Overview

This single-file application is a precision-oriented calculation tool designed for harmonica repair technicians, luthiers, and customizers. It enables users to input baseline comb measurements, material types, and environmental factors to predict swelling, ensuring final components maintain optimal airtight tolerances.

Core Features

• Dynamic Material Input: Dropdown selector featuring common materials (Pearwood, Bamboo, Doussie, Acrylic, Resin, ABS) with pre-loaded expansion coefficients.
• Environmental Settings: Input fields for baseline and target relative humidity (RH%) percentages.
• Real-Time Calculation: Instant updates to "Recommended Machining Thickness" as inputs change, utilizing a reactive UI approach.
• Precision Toggle: Switch between Millimeters (mm) and Inches (in) with high-precision decimal support (up to 3 decimal places).
• Measurement Reference: A built-in guide for standard harmonica comb tolerances.

UI/UX Design & Layout

• Clean, Light-Mode Aesthetic: Use a professional, high-contrast light theme. Backgrounds in cool grays (#F8FAFC) with white, elevated cards (#FFFFFF) using soft, professional box-shadows.
• Layout Structure:
  • Header: Simple, clean, centered text title and a brief sub-headline explaining the tool's purpose.
  • Main Container: A two-column grid on desktop (responsive to single column on mobile).
    • Left Column (Input): Grouped inputs for Material Type, Baseline Thickness, Humidity parameters.
    • Right Column (Output): A large, prominent display card showing the calculated final thickness, a graphical representation of the "swelling factor," and actionable advice based on the result.
  • Micro-interactions: Smooth CSS transitions on all input elements; subtle scaling animations when hovering over buttons.
• Typography: Use a clean, sans-serif font stack (Inter, system-ui) for readability.

Technical Constraints & Implementation

• Single File: All HTML, CSS, and Vanilla JavaScript must reside in one file.
• No Storage: Strictly no usage of localStorage or cookies. All calculations occur in the active JS memory heap.
• Security: CSP-compliant. No eval() or dangerous script patterns.
• Responsive: Fluid layout using CSS Grid/Flexbox. No rigid pixel widths.
• Libraries Allowed: Tailwind CSS (via CDN) for rapid, standardized styling and UI components. Font Awesome (via CDN) for clean, functional icons.

Implementation Steps

1. Setup: Create a standard HTML5 boilerplate with Tailwind CSS included in the head.
2. State Management: Use a simple JavaScript object to hold the current form data (state = { material: 'wood', baseline: 0, humidityStart: 45, humidityEnd: 70, unit: 'mm' }).
3. Calculation Engine: Create a function calculateExpansion() that triggers on any input change, updates the state, and re-renders the DOM elements to display results.
4. Rendering: Use template literals or vanilla DOM manipulation to update the results area without full page reloads.
5. Finishing Touches: Add accessibility (ARIA labels on inputs) and ensure color contrast meets WCAG accessibility standards.