frontend-conventions

name	frontend-conventions
description	Use when adding/editing routes, pages, Redux slices, or anything touching iTunes API data or audio playback in this repo (Music City). Encodes the project's established patterns so new code matches existing conventions instead of introducing new ones.

Music City frontend conventions

Reference CLAUDE.md first for architecture. This skill covers the concrete steps for common changes.

Adding a page/route

1. Add the path constant in src/pathes.tsx.
2. Add the <Route> in src/Router.tsx, pointing to a new file in src/pages/.
3. Page renders inside src/layout/SiteLayout.tsx (Navbar/Footer/MiniPlayer already wrapped) — don't re-add those.
4. Use @/ imports, never relative ../../.. chains.

Fetching iTunes data

• Never call itunes.apple.com / mzstatic.com / audio-ssl.itunes.apple.com directly.
• Build search URLs with itunesSearch() from src/utils/itunesApi.ts.
• Rewrite any artwork/audio URL returned by the API through proxyImageUrl() / proxyAudioUrl() before rendering/playing it — this is what makes it work through the dev proxy and the PWA Workbox cache rules in vite.config.ts.
• Static files in src/db/ are curation metadata only (genres, moods, playlist definitions) — never put live track data there.

Adding/editing Redux state

• One slice per domain in src/redux/<Domain>/<Domain>Slice.ts, registered in src/store.ts.
• Persisted UI state (favorites, theme, recently played) goes through src/utils/saveToLocal.ts / getFromLocal.ts, not a Redux persistence middleware — slices read the initial value from localStorage in their initial state and write on the relevant reducer.

Audio playback

• Never call new Audio() or touch an <audio> element directly from a component.
• src/utils/audioSingleton.ts owns the one HTMLAudioElement; src/components/AudioManager.tsx is the only place that drives it, reacting to src/redux/Player/PlayerSlice.ts.
• To play/pause/seek/change track from UI, dispatch Player slice actions (setIsPlaying, playNext, playPrev, etc.) — do not add a second audio element or bypass the slice.

Styling

• Tailwind CSS utility classes for layout/spacing/color; MUI only for the handful of components already using it (selects, etc.) — don't introduce a new component library.
• Respect the existing dark/light mode: theme state comes from src/hooks/useTheme.ts.

Before finishing

• npm run lint (max-warnings 0) and npm run build (tsc + vite build) should both pass — this is a TypeScript strict-mode project (noUnusedLocals, noUnusedParameters on).
• No test runner is configured; don't invent test commands.