# S03 Research: Featured Content & Content Teasers

## Depth: Light

Straightforward frontend work — adding two new homepage sections using established patterns and existing API endpoints. No new backend routes required; no unfamiliar technology.

## Summary

The homepage (Home.tsx, 306 lines) already has: hero section with tagline/value-prop/how-it-works, search bar with typeahead, nav cards, popular topics pills, and a "Recently Added" section fetching `GET /api/v1/techniques?limit=5` sorted by `created_at DESC`. The slice adds:

1. **Featured Technique Spotlight** — a prominent single-technique card above the recently-added section, highlighting one technique with more detail (summary, creator, tags, moment count).
2. **Enriched Recently Added cards** — upgrade the existing `recent-card` elements with richer visual treatment (summary preview, better badge layout, visual hierarchy).

## Recommendation

### Featured Technique Spotlight

No dedicated backend endpoint needed. Two viable approaches:

- **Option A (simple):** Fetch `GET /api/v1/techniques?limit=1` — gets the most recently created technique. Deterministic, zero backend changes.
- **Option B (random):** Add a `sort=random` parameter to the existing `list_techniques` endpoint (same pattern as `creators.py` line 67: `func.random()`), then fetch `?limit=1&sort=random`. Slightly more interesting UX — different technique on each visit.

**Recommendation: Option B.** The pattern is already established in the creators endpoint. Adding `sort` param to `/techniques` is a 5-line backend change. A rotating spotlight is more engaging and aligns with R014's creator equity spirit (no single technique permanently promoted).

### Enriched Recently Added

The existing `recent-card` already renders title, creator_name, topic_category badge, topic_tags pills, summary (truncated to 100 chars), and moment count. The `TechniqueListItem` type has all needed fields. Enrichment is purely CSS/layout:

- Wider card layout (current max-width: 36rem is narrow for cards with metadata)
- Grid layout instead of single-column stack (2 columns on desktop)
- More prominent summary text
- Better visual hierarchy between title and metadata

### No new API types needed

`TechniqueListItem` already includes: title, slug, topic_category, topic_tags, summary, creator_name, creator_slug, source_quality, key_moment_count. All fields needed for both the spotlight and enriched cards are present.

## Implementation Landscape

### Files to modify

| File | Change |
|------|--------|
| `backend/routers/techniques.py` | Add optional `sort` query param (random/recent, default recent) to `list_techniques` |
| `frontend/src/api/public-client.ts` | Add `sort` to `TechniqueListParams` |
| `frontend/src/pages/Home.tsx` | Add featured spotlight section, fetch with `sort=random&limit=1`; restructure recently-added layout |
| `frontend/src/App.css` | Add `.home-featured` spotlight styles, update `.recent-*` styles for grid layout and enriched cards |

### Existing patterns to follow

- **BEM naming under `.home-` prefix** (S01 pattern): `.home-featured__title`, `.home-featured__summary`, etc.
- **Optional data-driven sections silently hide on API error** (S01 popular topics pattern): featured section should not show error UI if fetch fails
- **CSS custom properties** from D017: `--color-accent`, `--color-bg-surface`, `--color-border`, `--color-badge-category-*`
- **Card hover transition**: `border-color 0.15s, box-shadow 0.15s` with `--color-accent-hover` / `--color-accent-subtle`

### Constraints

- Homepage hero section is `text-align: center` — the featured section should break from this with left-aligned content for readability
- Recently Added is currently `max-width: 36rem` — can widen to 42rem or match the how-it-works grid width for card grid
- The featured technique fetch is a separate API call from the recently-added fetch — need to exclude the featured technique from the recently-added list to avoid duplication (filter client-side by ID)

### Verification approach

- `cd frontend && npx vite build` — zero TypeScript errors
- Source inspection: confirm `.home-featured` section renders with spotlight technique data
- Source inspection: confirm recently-added uses grid layout with enriched card markup
- Visual inspection via browser if available
