From 3f3fe065f88efe789d5b68d2259cff205bad4fa4 Mon Sep 17 00:00:00 2001 From: jlightner Date: Mon, 30 Mar 2026 11:44:18 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20Added=20Music=20Theory=20as=207th=20cat?= =?UTF-8?q?egory=20in=20canonical=5Ftags.yaml=20with=208=E2=80=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - "config/canonical_tags.yaml" - "frontend/src/App.css" GSD-Task: S05/T01 --- .gsd/milestones/M006/M006-ROADMAP.md | 2 +- .../milestones/M006/slices/S04/S04-SUMMARY.md | 79 ++++++++++++++++ .gsd/milestones/M006/slices/S04/S04-UAT.md | 59 ++++++++++++ .../M006/slices/S04/tasks/T01-VERIFY.json | 30 ++++++ .gsd/milestones/M006/slices/S05/S05-PLAN.md | 36 +++++++- .../M006/slices/S05/S05-RESEARCH.md | 92 +++++++++++++++++++ .../M006/slices/S05/tasks/T01-PLAN.md | 30 ++++++ .../M006/slices/S05/tasks/T01-SUMMARY.md | 78 ++++++++++++++++ .../M006/slices/S05/tasks/T02-PLAN.md | 43 +++++++++ frontend/src/App.css | 3 + 10 files changed, 450 insertions(+), 2 deletions(-) create mode 100644 .gsd/milestones/M006/slices/S04/S04-SUMMARY.md create mode 100644 .gsd/milestones/M006/slices/S04/S04-UAT.md create mode 100644 .gsd/milestones/M006/slices/S04/tasks/T01-VERIFY.json create mode 100644 .gsd/milestones/M006/slices/S05/S05-RESEARCH.md create mode 100644 .gsd/milestones/M006/slices/S05/tasks/T01-PLAN.md create mode 100644 .gsd/milestones/M006/slices/S05/tasks/T01-SUMMARY.md create mode 100644 .gsd/milestones/M006/slices/S05/tasks/T02-PLAN.md diff --git a/.gsd/milestones/M006/M006-ROADMAP.md b/.gsd/milestones/M006/M006-ROADMAP.md index 711eca0..7808c7d 100644 --- a/.gsd/milestones/M006/M006-ROADMAP.md +++ b/.gsd/milestones/M006/M006-ROADMAP.md @@ -9,6 +9,6 @@ Consolidate admin navigation into a dropdown, add head/tail log viewing and comm | S01 | Admin Navigation Dropdown + Header Cleanup | low | — | ✅ | Header shows Home, Topics, Creators, and an Admin dropdown. Clicking Admin reveals Review, Reports, Pipeline links. ModeToggle removed from header. | | S02 | Pipeline Page: Head/Tail Log View + Token Count | low | — | ✅ | Pipeline event log shows Head/Tail toggle buttons. Head shows first N events, Tail shows last N events. Token counts visible per event and per video. | | S03 | Git Commit SHA in Pipeline Version Metadata | low | — | ✅ | Running the pipeline captures the current git commit SHA. Viewing a technique page version shows the commit hash in the metadata panel. | -| S04 | Technique Page: Sidebar Reorder, Creator Emphasis, Tag Polish | medium | — | ⬜ | Technique page sidebar shows Plugins Referenced at top. Creator name is visually prominent. Tags use a coherent color system. | +| S04 | Technique Page: Sidebar Reorder, Creator Emphasis, Tag Polish | medium | — | ✅ | Technique page sidebar shows Plugins Referenced at top. Creator name is visually prominent. Tags use a coherent color system. | | S05 | Topics Page Redesign + Music Theory Category | high | — | ⬜ | Topics page shows 7 categories (including Music Theory) with an improved visual layout — category cards with descriptions, sub-topic counts, better structure. | | S06 | App Footer with Version Info | low | — | ⬜ | Every page shows a subtle footer with app version, build date, and optional repo link. | diff --git a/.gsd/milestones/M006/slices/S04/S04-SUMMARY.md b/.gsd/milestones/M006/slices/S04/S04-SUMMARY.md new file mode 100644 index 0000000..c577ba5 --- /dev/null +++ b/.gsd/milestones/M006/slices/S04/S04-SUMMARY.md @@ -0,0 +1,79 @@ +--- +id: S04 +parent: M006 +milestone: M006 +provides: + - Technique page sidebar with plugins-first ordering + - Prominent creator block with genre pills + - Per-category badge color system (6 categories) +requires: + [] +affects: + [] +key_files: + - frontend/src/pages/TechniquePage.tsx + - frontend/src/App.css +key_decisions: + - Category slug conversion uses toLowerCase().replace(/\s+/g, '-') for CSS class derivation — matches common CSS naming convention and handles multi-word categories like 'Sound Design' → 'sound-design' +patterns_established: + - Per-category color system: CSS custom property pairs (--color-badge-cat-{slug}-bg/text) with matching utility classes (.badge--cat-{slug}), base class as fallback for unknown values +observability_surfaces: + - none +drill_down_paths: + - .gsd/milestones/M006/slices/S04/tasks/T01-SUMMARY.md +duration: "" +verification_result: passed +completed_at: 2026-03-30T11:35:20.065Z +blocker_discovered: false +--- + +# S04: Technique Page: Sidebar Reorder, Creator Emphasis, Tag Polish + +**Reordered technique page sidebar (plugins first), added prominent creator block with genre pills, and implemented per-category badge color system with 6 category-specific color pairs.** + +## What Happened + +Single-task slice that made three visual improvements to the technique page: + +**Sidebar reorder:** The Plugins Referenced section was moved to the top of the sidebar column, before Key Moments, Signal Chains, and Related Techniques. This puts the most actionable reference (what plugins to use) first. + +**Creator emphasis:** The creator name was extracted from the inline meta row and placed in a new dedicated `technique-header__creator-block` between the page title and the meta badges. The creator link is now 1.125rem / weight 600 with accent coloring. When the creator has genres, they render as small pills alongside the name. + +**Category badge colors:** Six per-category color pairs (sound-design, mixing, synthesis, arrangement, workflow, mastering) were added as CSS custom properties. Each category gets a `.badge--cat-{slug}` class applied dynamically via `displayCategory.toLowerCase().replace(/\s+/g, '-')`. The base `.badge--category` indigo style remains as fallback for any unrecognized category. + +## Verification + +TypeScript compilation (`cd frontend && npx tsc --noEmit`) passed with zero errors. Vite production build (`cd frontend && npx vite build`) succeeded — 47 modules transformed, built in 813ms. Grep verification confirmed: plugins section at line 418 (first in sidebar div at 415), creator-block at line 230 between h1 and meta div, 12 new CSS custom properties (6 categories × bg+text), 6 `.badge--cat-*` CSS classes, dynamic category class derivation in JSX. + +## Requirements Advanced + +- R006 — Technique page sidebar reordered for usability (plugins first), creator given visual prominence, category badges now color-coded per category + +## Requirements Validated + +None. + +## New Requirements Surfaced + +None. + +## Requirements Invalidated or Re-scoped + +None. + +## Deviations + +None. + +## Known Limitations + +The verification commands in the slice plan specify `cd frontend && npx tsc --noEmit && npx vite build` but the auto-mode verification gate ran them from the project root, causing false failures. The code itself is correct. + +## Follow-ups + +None. + +## Files Created/Modified + +- `frontend/src/pages/TechniquePage.tsx` — Moved plugins section to top of sidebar, added creator-block with genre pills between h1 and meta row, dynamic category badge class derivation +- `frontend/src/App.css` — Added 12 per-category CSS custom properties, 6 .badge--cat-* classes, creator-block/creator-link/pill--genre-small styles, removed old .technique-header__creator rules diff --git a/.gsd/milestones/M006/slices/S04/S04-UAT.md b/.gsd/milestones/M006/slices/S04/S04-UAT.md new file mode 100644 index 0000000..35034fc --- /dev/null +++ b/.gsd/milestones/M006/slices/S04/S04-UAT.md @@ -0,0 +1,59 @@ +# S04: Technique Page: Sidebar Reorder, Creator Emphasis, Tag Polish — UAT + +**Milestone:** M006 +**Written:** 2026-03-30T11:35:20.065Z + +# S04 UAT: Technique Page Sidebar, Creator, Tag Polish + +## Preconditions +- Chrysopedia web UI is accessible (http://ub01:8096) +- At least one technique page exists with: a creator that has genres, a recognized category (Sound Design, Mixing, Synthesis, Arrangement, Workflow, or Mastering), and at least one plugin referenced + +## Test Cases + +### TC-1: Sidebar Order — Plugins First +1. Navigate to a technique page that has plugins referenced +2. Scroll to the sidebar column (right side on desktop) +3. **Expected:** Plugins Referenced section appears FIRST in the sidebar, before Key Moments, Signal Chains, and Related Techniques + +### TC-2: Creator Block Placement and Styling +1. Navigate to any technique page with a creator +2. Observe the header area +3. **Expected:** Creator name appears between the page title (h1) and the category/tag badges row +4. **Expected:** Creator name is visually prominent — larger than body text, bold weight +5. Click the creator name +6. **Expected:** Navigates to the creator detail page (`/creators/{slug}`) + +### TC-3: Creator Genre Pills +1. Navigate to a technique page whose creator has genre tags (e.g., "Electronic", "Hip Hop") +2. **Expected:** Small genre pills appear next to the creator name in the creator block +3. **Expected:** Pills are compact (smaller font than body text) and don't dominate the creator name + +### TC-4: Creator Without Genres +1. Navigate to a technique page whose creator has no genre tags +2. **Expected:** Creator name renders normally without any genre pills — no empty container or visual artifact + +### TC-5: Per-Category Badge Colors +1. Navigate to technique pages across different categories: + - A Sound Design technique → badge should have teal text on dark teal background + - A Mixing technique → badge should have purple text on dark purple background + - A Synthesis technique → badge should have blue text on dark blue background + - An Arrangement technique → badge should have yellow text on dark brown background + - A Workflow technique → badge should have green text on dark green background + - A Mastering technique → badge should have pink text on dark magenta background +2. **Expected:** Each category has a distinct, readable color pair + +### TC-6: Unknown Category Fallback +1. If a technique page has a category not in the 6 known categories (or no category) +2. **Expected:** Badge renders with the default indigo `.badge--category` base style — no broken styling or missing colors + +### TC-7: Build Verification +1. Run `cd frontend && npx tsc --noEmit` +2. **Expected:** Zero TypeScript errors +3. Run `cd frontend && npx vite build` +4. **Expected:** Build succeeds with no errors + +## Edge Cases +- Technique page with no plugins: sidebar should not show an empty Plugins section +- Technique page with no creator_info: creator block should not render at all +- Category with spaces (e.g., "Sound Design"): badge class should be `badge--cat-sound-design` diff --git a/.gsd/milestones/M006/slices/S04/tasks/T01-VERIFY.json b/.gsd/milestones/M006/slices/S04/tasks/T01-VERIFY.json new file mode 100644 index 0000000..7dac6b5 --- /dev/null +++ b/.gsd/milestones/M006/slices/S04/tasks/T01-VERIFY.json @@ -0,0 +1,30 @@ +{ + "schemaVersion": 1, + "taskId": "T01", + "unitId": "M006/S04/T01", + "timestamp": 1774870454941, + "passed": false, + "discoverySource": "task-plan", + "checks": [ + { + "command": "cd frontend", + "exitCode": 0, + "durationMs": 5, + "verdict": "pass" + }, + { + "command": "npx tsc --noEmit", + "exitCode": 1, + "durationMs": 741, + "verdict": "fail" + }, + { + "command": "npx vite build", + "exitCode": 1, + "durationMs": 895, + "verdict": "fail" + } + ], + "retryAttempt": 1, + "maxRetries": 2 +} diff --git a/.gsd/milestones/M006/slices/S05/S05-PLAN.md b/.gsd/milestones/M006/slices/S05/S05-PLAN.md index e17d6d9..6d42df7 100644 --- a/.gsd/milestones/M006/slices/S05/S05-PLAN.md +++ b/.gsd/milestones/M006/slices/S05/S05-PLAN.md @@ -1,6 +1,40 @@ # S05: Topics Page Redesign + Music Theory Category -**Goal:** Add Music Theory to the taxonomy, update classification prompt, and redesign the Topics browse page +**Goal:** Topics page shows 7 categories (including Music Theory) in a responsive card grid layout with category descriptions, sub-topic counts, technique counts, expand/collapse, and filter — all using the existing API shape. **Demo:** After this: Topics page shows 7 categories (including Music Theory) with an improved visual layout — category cards with descriptions, sub-topic counts, better structure. ## Tasks +- [x] **T01: Added Music Theory as 7th category in canonical_tags.yaml with 8 sub-topics, plus warm orange-gold badge CSS in App.css** — Add "Music Theory" as the 7th category in `config/canonical_tags.yaml` on ub01 with appropriate sub-topics (harmony, chord progressions, scales, rhythm, time signatures, melody, counterpoint, song keys). Add corresponding CSS custom properties `--color-badge-cat-music-theory-bg` and `--color-badge-cat-music-theory-text` to the `:root` block in `frontend/src/App.css`, and add the `.badge--cat-music-theory` class rule after the existing `.badge--cat-mastering` line. Use a warm orange-gold palette (e.g., bg: #3b2506, text: #fdba74) that is visually distinct from the existing 6 category colors (teal, purple, blue, amber, green, pink). + +Steps: +1. SSH to ub01 and edit `/vmPool/r/repos/xpltdco/chrysopedia/config/canonical_tags.yaml` — add Music Theory category block after the Mastering entry, following the same YAML structure as existing categories. +2. Verify the API returns 7 categories: `curl -s http://ub01:8096/api/v1/topics | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d)); assert len(d)==7; print([c['name'] for c in d])"` +3. Edit `frontend/src/App.css` `:root` block (around line 99) — add two new custom properties for music-theory badge colors. +4. Edit `frontend/src/App.css` badge class section (around line 1206) — add `.badge--cat-music-theory` class. +5. Verify CSS is syntactically valid by running `cd frontend && npm run build`. + - Estimate: 15m + - Files: config/canonical_tags.yaml (on ub01 via SSH), frontend/src/App.css + - Verify: curl -s http://ub01:8096/api/v1/topics | python3 -c "import sys,json; d=json.load(sys.stdin); assert len(d)==7, f'Expected 7 categories, got {len(d)}'; names=[c['name'] for c in d]; assert 'Music Theory' in names, f'Music Theory not found in {names}'; print('PASS: 7 categories including Music Theory')" && cd frontend && npx grep-cli --no-error 'music-theory' src/App.css || grep -q 'music-theory' frontend/src/App.css && echo 'PASS: badge CSS present' +- [ ] **T02: Redesign TopicsBrowse.tsx to card grid layout with updated CSS** — Rewrite `TopicsBrowse.tsx` from the current vertical accordion list to a responsive card grid layout, and replace the topics CSS section in `App.css` with card-based styles. + +The card layout should: +- Use CSS grid: 2 columns on desktop (min-width > 768px), 1 column on mobile +- Each category card is a bordered surface with: category name (h3, prominent), description text, summary stats line showing sub-topic count and total technique count, expand/collapse button +- Expanded state reveals sub-topics inside the card as a list of links to `/search?q={name}&scope=topics` with technique and creator counts +- Filter input stays at the top, filtering which cards are visible +- All existing functionality preserved: expand/collapse toggle, filter matching on category name + sub-topic names, sub-topic → search navigation + +The technique count per category should be computed client-side by summing `sub_topics.map(st => st.technique_count)`. The `TopicCategory` type already has `description` and `sub_topics` with counts — no API changes needed. + +CSS changes: +- Replace `.topics-list` flex-column with CSS grid `grid-template-columns: repeat(2, 1fr)` + gap +- Restyle `.topic-category` as a card with padding, border-radius, subtle shadow +- Add `.topic-category__stats` for the summary stats line +- Keep `.topic-subtopics` and `.topic-subtopic` styles but adjust padding for card context +- Update `@media (max-width: 640px)` responsive rules for single-column grid +- Use category badge colors on the card (subtle left border or header accent) to create visual differentiation between categories + +The badge class for each category follows the pattern: `badge--cat-${name.toLowerCase().replace(/\s+/g, '-')}`. The corresponding CSS custom properties are `--color-badge-cat-{slug}-bg` and `--color-badge-cat-{slug}-text`. All 7 categories (sound-design, mixing, synthesis, arrangement, workflow, mastering, music-theory) have these defined in `:root`. + - Estimate: 45m + - Files: frontend/src/pages/TopicsBrowse.tsx, frontend/src/App.css + - Verify: cd frontend && npm run build 2>&1 | tail -5 && echo 'PASS: frontend builds' && ssh ub01 'curl -s http://localhost:8096/topics | grep -c "topic-category"' | grep -q '[0-9]' && echo 'PASS: topics page serves HTML' diff --git a/.gsd/milestones/M006/slices/S05/S05-RESEARCH.md b/.gsd/milestones/M006/slices/S05/S05-RESEARCH.md new file mode 100644 index 0000000..cf0a7f1 --- /dev/null +++ b/.gsd/milestones/M006/slices/S05/S05-RESEARCH.md @@ -0,0 +1,92 @@ +# S05 Research — Topics Page Redesign + Music Theory Category + +## Summary + +Two changes: (1) add "Music Theory" as the 7th category to `canonical_tags.yaml` and wire up corresponding CSS badge colors, (2) redesign `TopicsBrowse.tsx` from an accordion-list to a card-based layout with better visual hierarchy. + +The backend `/api/v1/topics` endpoint reads categories from `config/canonical_tags.yaml` and computes per-sub-topic technique/creator counts from the DB. Adding Music Theory is purely a YAML + CSS change — no backend code changes, no migrations. The frontend `TopicsBrowse.tsx` consumes the same `TopicCategory[]` API shape; the redesign is a CSS/JSX rewrite of that single component. + +## Requirement Alignment + +- **R008 (Topics Browse Page, validated):** This slice enhances an already-validated requirement. The current two-level hierarchy, filter, and sub-topic → search navigation all remain. The redesign improves visual presentation without changing functionality. + +## Implementation Landscape + +### Files to Modify + +| File | What Changes | +|------|-------------| +| `config/canonical_tags.yaml` (on ub01) | Add "Music Theory" category with sub_topics | +| `frontend/src/App.css` | Add `--color-badge-cat-music-theory-*` CSS custom properties + `.badge--cat-music-theory` class. Rewrite `.topics-browse`, `.topic-category`, `.topic-subtopics` styles for card layout. | +| `frontend/src/pages/TopicsBrowse.tsx` | Redesign JSX structure from accordion list to card grid. Keep filter, expand/collapse, and sub-topic → search links. | + +### Files That Stay the Same (No Changes Needed) + +- `backend/routers/topics.py` — reads from canonical_tags.yaml dynamically, no code changes needed +- `backend/schemas.py` — `TopicCategory` / `TopicSubTopic` schemas are fine as-is +- `frontend/src/api/public-client.ts` — `TopicCategory` type and `fetchTopics()` remain unchanged +- `frontend/src/App.tsx` — `/topics` route stays the same + +### Backend Endpoint Behavior + +The `GET /api/v1/topics` endpoint in `backend/routers/topics.py`: +- Reads categories from `config/canonical_tags.yaml` at request time (not cached) +- Pre-fetches all TechniquePage rows and counts per-sub-topic by matching `topic_tags` array contents +- Returns `TopicCategory[]` with `name`, `description`, `sub_topics[{name, technique_count, creator_count}]` + +Response shape does NOT need to change. The frontend type `TopicCategory` already includes `description` — it's just underutilized in the current accordion header. + +### Current Topics Page Layout + +Current layout is a flat vertical accordion: +- Page title + subtitle + filter input +- List of category "rows" — each is a `