moving

docs/briefs/2026-04-22-cc-personas-card-component-parallel.md

@@ -0,0 +1,221 @@
+# CC-2 Brief — Personas Card Component (Parallel Terminal)
+
+**Author:** PM
+**For:** Claude Code (waggle-os repo, second terminal, parallel to CC-1 Sprint 10 close-out)
+**Date:** 2026-04-22
+**Task:** Task #18 (Regen Brand-Bee personas card) implementation phase
+**Priority:** Medium (non-blocking za Sprint 10; unblocks landing implementation post-launch prep)
+**Budget:** $0 (pure local implementation, zero API spend)
+**Wall-clock:** 2-4h CC time
+
+---
+
+## Critical boundary — CC-1 non-interference
+
+CC-1 je aktivan na Sprint 10 parallel close-out (Task 1.1 live-run + Task 1.5 Phase 2+3). CC-1 radi na:
+- `packages/server/src/benchmarks/**` — benchmark harness
+- `packages/memory-mcp/**` ili `packages/core/**` — hive-mind ClaudeAdapter
+- `preflight-results/**` — results artifacts
+- `sessions/**` — exit pings
+
+**CC-2 MORA da ostane u `apps/www/**` tree-u.** Ne dodiruj `packages/`, `preflight-results/`, `sessions/`, ili bilo koji drugi folder van `apps/www/`. Ako trebaš shared utility (npr. type definicija iz `packages/core`), importuj preko postojeće path mapping-a, ne kreiraj novu zavisnost.
+
+Specifično dozvoljeni paths za write:
+- `apps/www/src/components/**`
+- `apps/www/src/data/**`
+- `apps/www/src/app/design/personas/**`
+- `apps/www/src/types/**` (ako ne postoji već)
+- `apps/www/__tests__/**` ili equivalent test folder koji repo koristi
+
+---
+
+## Scope
+
+Implementiraj `BrandPersonasCard` React komponentu sa svim downstream implementacionim implikacijama iz `decisions/2026-04-22-landing-personas-ia-locked.md` Decision 3. Komponenta mora biti spreman za landing integration + reusable za buduće product contexts (onboarding, pricing section snippets) kroz `variant` prop.
+
+Svi copy strings dolaze iz ratifikovanog izvora — NE reinterpretiraj, NE polish, NE rewriting.
+
+---
+
+## Authoritative source files (CC čita, ne menja)
+
+1. **Component contract:** `D:\Projects\PM-Waggle-OS\briefs\2026-04-22-brand-bee-personas-card-spec.md` — scaffold spec (updated 2026-04-22 sa ratifikovanim copy-om)
+2. **Copy LOCKED:** `D:\Projects\PM-Waggle-OS\decisions\2026-04-22-personas-card-copy-locked.md` — 13 canonical role titles + JTBD strings
+3. **Landing IA LOCKED:** `D:\Projects\PM-Waggle-OS\decisions\2026-04-22-landing-personas-ia-locked.md` — component contract implikacije (variant prop, onTileHover, CTA prop, reusable data source)
+4. **Asset canon:** `D:\Projects\waggle-os\apps\www\public\brand\bee-*-dark.png` (11 canon + 2 pending from Task #24)
+5. **Design system tokens:** `D:\Projects\waggle-os\apps\www\src\styles\globals.css` (already contains Hive DS tokens per 2026-04-20 setup)
+
+---
+
+## Deliverables
+
+### 1. Data source — `apps/www/src/data/personas.ts`
+
+TypeScript module koji izvozi `personas` const kao read-only tuple sa 13 entry-ja. Copy MUST come verbatim from `decisions/2026-04-22-personas-card-copy-locked.md` canonical table.
+
+```ts
+export interface Persona {
+  slug: PersonaSlug;
+  title: string;         // "The Hunter"
+  role: string;          // "Finds the source you forgot you saved."
+  alt: string;           // accessible label for img — "Waggle {title} bee mascot"
+  imagePath: string;     // "/brand/bee-hunter-dark.png"
+  order: number;         // 1-13, canonical reading order
+}
+
+export type PersonaSlug =
+  | "hunter" | "researcher" | "analyst" | "connector" | "architect"
+  | "builder" | "writer" | "orchestrator" | "marketer" | "team"
+  | "celebrating" | "confused" | "sleeping";
+
+export const personas: readonly Persona[] = [
+  // 13 entries, ordering from decision log
+] as const;
+```
+
+Slug mapping za image path:
+- `hunter` → `/brand/bee-hunter-dark.png`
+- `researcher` → `/brand/bee-researcher-dark.png`
+- `analyst` → `/brand/bee-analyst-dark.png`
+- `connector` → `/brand/bee-connector-dark.png`
+- `architect` → `/brand/bee-architect-dark.png`
+- `builder` → `/brand/bee-builder-dark.png`
+- `writer` → `/brand/bee-writer-dark.png`  ← **placeholder state until Task #24 deploy**
+- `orchestrator` → `/brand/bee-orchestrator-dark.png`
+- `marketer` → `/brand/bee-marketer-dark.png`
+- `team` → `/brand/bee-team-dark.png`
+- `celebrating` → `/brand/bee-celebrating-dark.png`
+- `confused` → `/brand/bee-confused-dark.png`
+- `sleeping` → `/brand/bee-sleeping-dark.png`  ← **placeholder state until Task #24 deploy**
+
+### 2. Component — `apps/www/src/components/BrandPersonasCard.tsx`
+
+Functional React component, default export, zero required props.
+
+```ts
+export interface BrandPersonasCardProps {
+  heading?: string;                                     // default "The Waggle Hive"
+  subtitle?: string;                                    // default: see below
+  showFillerTiles?: boolean;                            // default true
+  variant?: "landing" | "compact";                      // default "landing"
+  onTileHover?: (slug: PersonaSlug) => void;            // default no-op
+  onPersonaClick?: (slug: PersonaSlug) => void;         // default no-op
+  cta?: React.ReactNode;                                // optional CTA slot rendered below grid
+}
+```
+
+Default subtitle: `"Thirteen personas for the work your AI does while you sleep."`
+
+**Variant behavior:**
+- `"landing"` — full 13-tile grid, responsive (4×4 + 3 fillers on ≥1024px, 3×5 on 768-1023px, 2×7 on <768px), includes heading + subtitle + CTA slot
+- `"compact"` — stub implementation sa TypeScript-valid return ali renderuje TODO placeholder div. NE implementiraj puni compact layout u ovom sprintu; samo interface plumbing. Dodaj JSDoc `@todo compact variant scaffolding — implement in future sprint`.
+
+**Tile anatomy (verbatim iz scaffold spec-a):**
+- Background: hive-gradient `#0f1218` → `#080a0f`, 1px border `#1a1e27`
+- Hover: border transition to `#e5a000`, scale 1.02, 200ms ease-out, respects `prefers-reduced-motion`
+- Asset render: 256×256 area, centered, object-fit contain, `next/image` ako se koristi u repo-u
+- Role title: Inter 16/600, color `#f5b731`
+- Role line: Inter 13/400, color `#a0a3ad`
+
+**Filler tiles:** 3 angular positions sa `hex-texture-dark.png` at 40% opacity, no copy, aria-hidden.
+
+**Accessibility:**
+- Grid je `<ul role="list">` sa `<li>` tile-ovima
+- Each tile je `<figure>` sa `<img>` + `<figcaption>`
+- Alt text iz `persona.alt` field
+- `:focus-visible` outline `#e5a000` 2px za keyboard korisnike
+- `aria-label` na CTA slot ako je prosleđen
+
+**Placeholder handling za pending asseti (writer, sleeping):**
+
+Proveri postojeći file state asset-a pri buildu. Ako asset ne postoji (ili je fallback detekcija on-mount), render fallback state:
+- Tile zadržava strukturu i copy
+- Umesto 256×256 asset-a, prikazi centered `<div>` sa hex-texture background-om i honey-400 "●" dot placeholder-om, 48×48 centered
+- Dodaj `data-placeholder="true"` attribute za lakše testiranje
+
+Ovo treba da radi korektno dok Task #24 ne CLOSE i writer + sleeping asseti ne budu deploy-ovani. Posle Task #24 CLOSE, placeholder automatski prestaje da se prikazuje bez code change-a (asset postoji → render normal).
+
+### 3. Preview route — `apps/www/src/app/design/personas/page.tsx`
+
+Izolovani preview route za visual QA i hand-off. Renderuje `<BrandPersonasCard variant="landing" />` na full-page hive background (`#08090c`). No header, no footer, no navigation — čista prezentacija.
+
+Dodaj noindex meta tag ako framework podržava (sprečava SEO indeksaciju preview route-a).
+
+### 4. Tests — `apps/www/__tests__/BrandPersonasCard.test.tsx` (ili equivalent repo convention)
+
+Minimum test coverage:
+1. Component renders 13 persona tiles + 3 filler tiles by default
+2. Each persona tile contains correct title + role copy (check all 13)
+3. `onPersonaClick` fired sa pravilnim slug kada se tile klikne
+4. `onTileHover` fired sa pravilnim slug na mouseover
+5. `cta` prop renders u CTA slot
+6. `showFillerTiles={false}` skida filler tiles iz render-a
+7. Placeholder state renders za pending asset (mock missing file)
+8. Compact variant renders bez error-a (basic smoke test)
+
+Use repo existing test runner (Jest + RTL ako je to standard; vitest ako je to standard). Check `package.json` i `apps/www/package.json` pre nego što odabereš.
+
+### 5. Export hygiene
+
+Dodaj barrel export u `apps/www/src/components/index.ts` (ako postoji) ili kreiraj. Također osiguraj da tip `PersonaSlug` i interface `Persona` budu eksportovani iz `apps/www/src/data/personas.ts` za buduće cross-file use.
+
+---
+
+## Exit criteria
+
+- [ ] `personas.ts` data source committed sa svih 13 canonical entries
+- [ ] `BrandPersonasCard.tsx` component fully implemented sa `landing` variant; `compact` variant je stub sa TODO
+- [ ] Preview route `/design/personas` renders clean 13-tile grid sa 3 filler-a u browser-u
+- [ ] Tests pass sa ≥8 test case-ova covered
+- [ ] Placeholder handling verified — writer + sleeping render u placeholder stanju bez JavaScript errora (jer trenutno još uvek imaju white-dominant PNGs; kad Task #24 CLOSE-uje i novi PNGs budu deploy-ovani, placeholder ne bi trebao da se aktivira)
+- [ ] `next build` (ili repo equivalent) prolazi bez error-a
+- [ ] Exit ping u `sessions/2026-04-22-personas-card-component-exit.md` sa:
+  - Preview route screenshot 1024px viewport
+  - Test run pass count
+  - Build output clean
+  - List all files created/modified
+  - Placeholder state screenshot (show writer + sleeping u placeholder mode-u)
+
+---
+
+## PM review gate
+
+CC-2 NE commit-uje direktno na main niti ne push-uje na origin. Posle svih exit criteria PASS, CC-2 priprema branch (npr. `feat/personas-card-component`) sa svim izmenama commit-ovanim i posta exit ping. PM review-uje diff, potvrđuje, i daje go-signal za merge + push.
+
+---
+
+## Anti-pattern check
+
+- Ne reinterpretiraj copy — verbatim iz decision log-a
+- Ne menjaj scaffold spec layout values (gradient colors, Inter weights, gap, container max-width)
+- Ne implementiraj `/bees/<slug>` subpage rute — LOCKED decision je bez subpage-a v1
+- Ne uvodi nove dependencies u package.json (sve mora raditi sa postojećim Tailwind + React + next/image stack-om)
+- Ne dodiruj fajlove van `apps/www/` tree-a
+- Ne commit-uj bez PM review-a
+- Ne push na origin autonomno
+- Ne scope-creepuj u pricing copy, hero copy, ili druge landing sekcije — samo personas card
+
+---
+
+## Escalation triggers
+
+1. **Build breakage** — IMMEDIATE PM ping, stash uncommitted work
+2. **Test failure koja ne može da se reši u ≤30 min** — PM ping, opisi fail
+3. **Dependency missing** (npr. Tailwind token nije pronađen) — PM ping, ne dodavaj new dependency autonomously
+4. **Asset path mismatch** (npr. PNG fajlovi ne postoje na očekivanim putanjama) — PM ping, ne kreiraj stub PNG-ove
+5. **TypeScript error koju copy-from-brief ne rešava** — PM ping
+6. **Waggle-os CC-1 touch any file CC-2 just modified** (git conflict) — STOP, PM ping, ne force-resolve
+
+---
+
+## Related
+
+- `briefs/2026-04-22-brand-bee-personas-card-spec.md` — scaffold spec (layout, tile anatomy)
+- `decisions/2026-04-22-personas-card-copy-locked.md` — copy LOCKED
+- `decisions/2026-04-22-landing-personas-ia-locked.md` — component contract implikacije (Decision 3)
+- `briefs/2026-04-22-cc-bee-regen-execution.md` — sibling CC brief (post-Sprint-10 execution)
+- `.auto-memory/feedback_repo_access_boundaries.md` — waggle-os write governance
+
+---
+
+**End of brief. CC-2 autonoman do exit ping-a. PM review gate ispred merge-a. No cross-talk sa CC-1.**