# 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 `<button>` header with chevron, name, description, count
- Expand reveals sub-topics as horizontal rows with name + counts
- Sub-topics link to `/search?q={name}&scope=topics`

### Proposed Card Layout

Redesign to a responsive card grid (2-column on desktop, 1-column on mobile):
- Each category becomes a card with:
  - Category name (prominent heading)
  - Description text
  - Total sub-topic count + total technique count as summary stats
  - Expand/collapse to show sub-topics inside the card
- Each sub-topic inside the card links to search as before
- Filter input stays at top, filtering cards

### CSS Badge Color Pattern

Category badge colors are derived dynamically: `badge--cat-${name.toLowerCase().replace(/\s+/g, '-')}` (in `TechniquePage.tsx` line 244). For "Music Theory" this generates `badge--cat-music-theory`.

Need to add to `:root`:
```
--color-badge-cat-music-theory-bg: <color>;
--color-badge-cat-music-theory-text: <color>;
```
And `.badge--cat-music-theory` class.

Existing 6 category color palette uses teal, purple, blue, amber, green, pink. Music Theory could use a warm orange-gold or a distinct slate-blue to differentiate.

### Music Theory Sub-Topics

Reasonable sub-topics for a music production knowledge base: harmony, chord progressions, scales, rhythm, time signatures, melody, counterpoint, song keys.

### Deployment Note

The canonical file lives at `/vmPool/r/repos/xpltdco/chrysopedia/config/canonical_tags.yaml` on ub01. The Docker container mounts this via bind mount. After editing, the API picks up the change on next request (no restart needed). Frontend changes require `docker compose build chrysopedia-web-8096 && docker compose up -d chrysopedia-web-8096`.

## Recommendation

Three tasks, ordered by risk:

1. **Add Music Theory category to canonical_tags.yaml + CSS badge colors** (~15min). Edit YAML on ub01, add CSS custom properties and badge class. Verify API returns 7 categories. This is the riskiest piece because it touches shared config — but the risk is low.

2. **Redesign TopicsBrowse.tsx component** (~30min). Rewrite JSX to card grid layout. Keep all existing behavior (filter, expand/collapse, sub-topic links). This is the bulk of the work.

3. **Rewrite topics CSS for card layout** (~20min). Can be combined with task 2 since CSS and JSX are tightly coupled. Replace `.topics-list` vertical stack with CSS grid, restyle `.topic-category` as cards, update responsive breakpoints.

Tasks 2 and 3 should probably be a single task since JSX structure and CSS are interdependent. The natural decomposition is:
- T01: YAML + CSS badge tokens (backend config + frontend styling)
- T02: TopicsBrowse.tsx + topics CSS redesign (frontend component rewrite)
- T03: Verification — build, deploy, visual check of 7 categories in card layout
