Technical Specification: Interactive Piano Chords Dictionary and Player

Overview

A high-fidelity, client-side web application designed to help musicians visualize, study, and hear piano chords. The application provides an interactive, virtual keyboard, allowing users to select roots and chord qualities to generate immediate visual and auditory feedback.

Core Features

• Dynamic Chord Selection: Intuitive dropdown or button-based controls to select Root (C through B) and Quality (Major, Minor, Diminished, Augmented, Suspended, 7th, 9th, etc.).
• Virtual Keyboard Visualization: A responsive, interactive SVG or CSS-based piano keyboard component. When a chord is selected, corresponding keys are highlighted with distinct colors.
• Web Audio Synthesis: Integrated synthesizer using the Web Audio API to play the selected chord. Includes volume control and basic ADSR envelope to ensure a clean, piano-like decay.
• Note Display: A clear textual representation of the notes present in the selected chord (e.g., C - E - G).
• Inversion Support: Toggle options to cycle through root position and inversions.

UI/UX Specification

• Aesthetic: Clean, professional "SaaS" aesthetic. Light mode exclusively (e.g., #F8FAFC background). Uses subtle shadows (shadow-sm, shadow-md) and modern typography (Inter or System UI sans-serif).
• Layout:
  • Header: Simple, descriptive H1 title.
  • Main Interaction Area: Controls positioned at the top or side, containing clear, labeled selects for chord parameters.
  • Visualizer: The keyboard centered horizontally, responsive to screen width.
  • Feedback Section: A clean card displaying the chord name and constituent notes.
• Interactions:
  • Smooth transition animations (300ms) when switching between chords to fade key highlights in and out.
  • High-contrast visual feedback on the piano keys when clicked or generated.

Technical Constraints & Implementation

• Architecture: Single-file HTML5 document. All logic (Vanilla JS), styles (Tailwind CSS CDN link), and structure in one file.
• Audio Engine: Purely browser-based using the AudioContext API. No external audio files to ensure fast loading and reliable operation.
• State Management: Use in-memory JavaScript state variables to store current selection. ABSOLUTELY NO localStorage, sessionStorage, or cookies.
• Responsiveness: Use CSS Grid and Flexbox to ensure the keyboard collapses appropriately for smaller screens while maintaining touch-friendly key sizes.
• Performance: Use requestAnimationFrame for any visual updates. Ensure event listeners are properly managed to prevent memory leaks.
• Sandbox Safety: The application must operate under the assumption of a null-origin iframe (no external API dependencies, no popup triggers).