MetaChordz: A Browser Music-Theory Workstation That Spells Its Own Chords
A chord-progression generator built as a vintage hardware synth — one that voices, spells, and names its harmony correctly across every key, and teaches the theory while you play.
Product Engineering & Interactive Audio
Solo project (ongoing)
Solo Design & Front-End Engineer
The business problem
Most chord generators output four notes and stop; full DAWs bury harmony behind a wall of tracks. Neither one helps the producer who can hear a ii–V–I but can't yet name it. MetaChordz had to do two genuinely hard things at once. First, generate progressions that are actually correct — not just pitches that sound fine, but chords that are voiced for smooth motion, spelled the way a musician reads them, and functionally labelled — and stay correct across all twelve keys and six modes. Second, narrate that harmony as it plays, in plain roman numerals and chord function, inside an interface tactile enough that theory feels like something you reach out and turn rather than a table you read.
Approach
- 01
Build the harmony as a pure, deterministic TypeScript library with no runtime dependencies, so correctness could be pinned by unit tests instead of eyeballed by ear.
- 02
Spell every chord tone by its musical context — letter plus accidental for the scale degree it occupies — rather than by pitch class, because a note name and a piano key are not the same thing.
- 03
Drive the entire interface from one design-token source, so a workstation this dense reads as engineered rather than assembled by hand.
What I built and changed
A Theory Engine, Not a Lookup Table
The core is a pure-TypeScript harmony library: diatonic generation across six scales with thirty-plus chord qualities, voice-leading, inversions, functional turnarounds, and roman-numeral analysis — all deterministic and covered by unit tests so the music stays correct in every key.
- Rebuilt note naming to spell by letter and accidental from context, so a tritone substitution renders D♭ F A♭ C♭ instead of a nonsensical C♯ …, and modal roots come out right — Phrygian ♭II, Dorian ♭III.
- Wrote voice-leading that scores candidate voicings for the smallest total movement from the previous chord, so progressions glide between shapes instead of leaping.
- Made turnarounds functional rather than cosmetic: the eight-bar cadence resolves through a leading-tone vii°7 or a ♭II7 tritone sub, each labelled correctly in the analysis panel.
One Source of Truth for Every Pixel
The UI started as hand-assembled markup — a dozen scattered hex values, duplicated components, off-grid spacing. I refactored it into a real design system so nothing was declared twice.
- Collapsed the palette into twenty-one named tokens stored once as RGB channels in :root, consumed from a single definition by both the Tailwind config (markup) and a token() helper (the spectrum canvas, which can't use CSS classes).
- Snapped spacing to a 4px grid and radii to a 2/4/8 scale, and extracted repeated chrome — panel headers, status pills — into shared components.
- Left a grep for a raw hex returning only the two gradient ramps I deliberately kept; change the brand red in one line now and the chord pads, the piano glow, and the spectrum all move together.
An Instrument You Operate, Not a Form You Fill
The vintage-workstation metaphor drives every interaction: hit a pad to sound a chord, watch the notes light on a three-octave keyboard, read its function in the analysis screen, feel the mix on a live spectrum.
- Aligned every element — logo, controls, panels, and pads — to a single content rail, the detail that separates a layout that looks fine from one that reads as hardware-grade.
- Made the panel deck flex with viewport height rather than a fixed size, so the chord pads shrink gracefully instead of clipping, from a phone in the hand to an ultrawide display.
- Ran the spectrum analyzer on requestAnimationFrame with smoothed peaks, reading the same color tokens as the rest of the UI, and gave each of seven genres its own scales, voicings, and hand-written progression templates.
Business results
A deterministic, test-covered harmony engine that stays correct across all twelve keys and six modes, with zero runtime dependencies for the theory itself.
A token-driven, fully responsive interface where every color is declared exactly once and consumed by both markup and canvas from the same source.
A fast, dependency-light web app on React 19, TypeScript, Tone.js, and Vite, with the theory layer pinned by a Vitest suite.
A workstation that teaches in the flow — roman numerals, chord function, inversion, and an emotional read appear the instant a chord is selected.
What the work proved
In a creative tool, 'sounds right' and 'is right' are not the same guarantee. The black key between A and B is A♯ in one chord and B♭ in the next, and a generator that ignores the difference produces harmony that plays fine and reads as gibberish to any musician. The fix wasn't more notes — it was spelling each one from the context it lives in, and pinning that in tests so the next chord quality I add can't quietly break the spelling of the ones already there.