UAT: Card Pack Migration + Deck Builder

1. Evidence & Source Coverage

Current Implementation State

Surface	Status	Source
Sealed pack tear-to-open	Implemented in prototype	`src/components/SealedPack.tsx` — drag-X gesture, curl effect, threshold trigger
Card fan-out	Implemented in prototype	`src/components/PackOpener.tsx` — spring-based fan offsets, rotation jitter
Card flip with benchmark grades	Implemented in prototype	`src/components/SkillCard.tsx` + `CardFace.tsx` — 3D rotateY, A/B/C grade display
Bottom sheet drawer	Implemented in prototype	`src/components/BottomSheet.tsx` — slide-up, drag-to-dismiss, scrim
Close sequence (7 phases)	Implemented in prototype	`animationMachine.ts` — sealed → opening-apex → drawer-open → closing-collapse → closing-apex → sheet-exiting → card-settling
Debug harness	Live at `/prototype`	`app/prototype/page.tsx` — DebugProvider, DebugPanel, imperative drivers
Homepage	Static layout	`app/page.tsx` — hero blueprint panel, CTA links, no card pack UI
/packs page	Static layout	`app/packs/page.tsx` — filter buttons, static pack summary, no animations
/catalog page	Static layout	`app/catalog/page.tsx` — search/filter, static rows, no card interactions
Deck builder	Not implemented	Roadmap references VARD, ORD, Business AFPS, Devtool AFPS decks with manifest metadata

Research Evidence Used

research/devtool-user-map.md — 3 persona shapes: solo builder, repo-embedded contributor, hybrid-mode orchestrator
research/devtool-dx-journey.md — install → quickstart → first success → error recovery → production adoption
specs/skills-showcase-website.md — site goals, IA, animation system, visual language
specs/ui-skills-showcase-website.md — page inventory, component inventory, responsive behavior
specs/ui-final-skills-showcase.md — playful blueprint theme consolidation, coral/teal accents
tasks/roadmap.md — deck metadata (VARD, ORD, Business AFPS, Devtool AFPS), skillpacks install-deck

Evidence Gaps

Deck builder UX spec does not exist yet. The roadmap defines deck metadata and CLI install semantics, but no visual spec describes drag-and-drop deck building, card slot layouts, or workflow sequence validation in the browser.
No user testing data from the prototype. The /prototype page exists but no recorded usability observations are available.
Mobile touch behavior is untested. The SealedPack drag gesture uses framer-motion drag, but no touch-device testing evidence exists.

2. Target User Personas

Persona A: Developer Evaluating Skillpacks

Role: Solo builder or DX lead considering agentic-skills adoption
Job-to-be-done: Understand what skills are available, see benchmark quality evidence, decide whether to adopt specific packs
Context: Arrives from GitHub README, LexCorp, or search. Has 5-10 minutes of attention. Needs to see value before installing anything.
Acceptance threshold: Can find a relevant pack, open it, read card details including benchmark grades, and understand the skill's purpose within 2 minutes per pack

Persona B: Content Creator Browsing Collections

Role: Non-technical or semi-technical user exploring the catalog visually
Job-to-be-done: Browse skill collections, understand categories at a glance, share interesting finds
Context: Arrives from YouTube, X/Twitter, or Discord. Drawn by card aesthetics. May not install anything but should leave understanding what G Skillpacks offers.
Acceptance threshold: Can navigate between packs, open and close multiple packs without confusion, understand skill categories from card visuals alone

Persona C: Power User Building Workflow Decks

Role: Experienced agentic-skills user who already runs plan → run → ship cycles
Job-to-be-done: Compose custom workflow sequences by dragging skill cards into named decklists (VARD, ORD, Business AFPS, Devtool AFPS)
Context: Knows the pack system. Wants to visualize and share their workflow combos. Expects Hearthstone-style collection management.
Acceptance threshold: Can build a deck of 5+ skills, reorder them, see the workflow sequence validated, and persist the deck across page reloads

3. Card Pack Migration Journeys

Journey 1: First-Visit Pack Discovery (Persona A)

User goal: Understand what skill packs exist and what they contain
Trigger: Developer clicks "Explore the Library" from homepage hero or navigates to /packs
Setup: Fresh browser session, no prior visits, desktop viewport (1280px+)

Task Sequence

Land on homepage. Verify the hero section loads with card pack visual elements (not the old static blueprint panel).
Identify at least 3 sealed packs visible on the page without scrolling (or within one scroll on smaller viewports).
Hover over a sealed pack. Verify the pack shows a visual affordance that it can be opened (cursor change, hover lift, or label).
Click a sealed pack to open it. Observe: does the tear-to-open animation play? Does the pack visually "unseal"?
Wait for the card fan-out animation. Count the cards revealed. Verify the fan-out completes without visual glitches (no overlapping cards stuck mid-animation, no cards appearing outside the viewport).
Read the first card's front face. Verify: skill name is legible, type badge is visible, benchmark grade (A/B/C) is displayed if the skill has benchmark data, command syntax is shown.
Click a card to flip it. Verify: the 3D flip animation is smooth (no visual tearing), the back face shows description, platform, scope, pack, version, and tags.
Click the card again to flip back to front.
Close the pack (tap scrim, drag drawer down, or use close affordance). Verify the full close sequence plays: cards collapse to a stack, stack rises to apex, bottom sheet slides out, card settles back to sealed position.
Verify the pack now shows an "opened" visual state (torn envelope, different styling from unopened packs).
Navigate to /catalog. Verify skills from the opened pack are browseable in the catalog view.

Acceptance Criteria

Sealed packs are visually distinguishable and named
Tear-to-open animation completes in under 800ms with no frame drops visible to the eye
Card fan-out displays all pack skills without overflow or clipping
Card front face shows: name, type, command, benchmark grade (when available), description preview
Card flip animation is smooth 3D rotation (no z-fighting or flicker)
Close sequence completes all 4 phases (collapse, apex rise, sheet exit, card settle) without stalling
Opened pack retains its opened visual state after closing
Total time from click-to-open to all cards visible is under 1.5 seconds

Non-Acceptance Signals

Cards appear instantly without animation (animation system not wired up)
Pack opens but close button/gesture is not discoverable within 5 seconds
Benchmark grade is missing on cards that have benchmark data in the source
Text on cards is too small to read without zooming (below 10px effective)
Animation stutters or janks (visible frame drops during fan-out or close)
Pack opens and the browser becomes unresponsive or sluggish

Evidence to Capture

Screen recording of full open → browse → flip → close cycle (include browser FPS overlay if possible)
Screenshot of card front face showing benchmark grade
Screenshot of card back face showing full metadata
Note: time from click to all cards visible
Note: any animation frame drops or visual glitches

Tester Notes Prompt

"As a developer evaluating whether to adopt this skill library, did the pack-opening experience help you understand what's inside each pack? Would you open a second pack, or would you switch to a list/table view?"

Journey 2: Touch-Device Pack Interaction (Persona B)

User goal: Browse and open skill packs on a phone or tablet
Trigger: Content creator taps a link from X/Twitter or Discord on their phone
Setup: Mobile device or tablet (real device preferred, simulator acceptable). iOS Safari and Android Chrome. Portrait orientation.

Task Sequence

Load the homepage on mobile. Verify sealed packs render in a scrollable layout (not cut off or overlapping).
Attempt the tear gesture: place finger on a sealed pack and drag horizontally. Verify the tear/curl visual effect follows the finger position.
Complete the tear past the threshold. Verify the pack opens and the bottom sheet slides up with the card fan-out.
Scroll through the cards in the drawer. Verify scrolling is smooth and does not accidentally dismiss the drawer.
Tap a card to flip it. Verify the tap target is large enough (44px minimum) and the flip triggers reliably on first tap.
Attempt to dismiss the drawer by dragging it down. Verify the drag-to-dismiss threshold feels natural (not too sensitive, not too stiff).
Rotate the device to landscape. Verify the layout reflows without breaking the card grid or cutting off content.
Open a different pack. Verify the previous pack shows its opened state.

Acceptance Criteria

Tear gesture works with touch (not just mouse drag)
Bottom sheet does not conflict with browser pull-to-refresh or back gesture
Card tap targets meet 44px minimum touch target size
Drawer scroll does not accidentally dismiss the drawer
Cards are legible without pinch-to-zoom on a 375px-wide viewport
Orientation change does not break layout or lose open/close state
No iOS Safari rubber-banding conflicts with the bottom sheet drag

Non-Acceptance Signals

Tear gesture does not register on touch devices (mouse-only implementation)
Drawer dismisses when user tries to scroll card content
Cards overlap or stack incorrectly on small viewports
Text requires pinch-to-zoom to read
Pull-to-refresh fires when dragging the tear gesture upward

Evidence to Capture

Screen recording on iOS Safari and Android Chrome
Screenshot of card layout at 375px width
Note: which touch gestures conflicted with browser defaults (if any)
Note: was the tear direction intuitive without instruction?

Tester Notes Prompt

"Did you understand how to open a pack without reading instructions? Did any gesture feel like it was fighting the phone's native behavior (scrolling, back, refresh)?"

Journey 3: Multi-Pack Browse & Compare (Persona A)

User goal: Open multiple packs, compare skills across them, find a specific skill
Trigger: Developer wants to compare the "Market Intel" and "Domain Decks" sets to decide which packs to install
Setup: Desktop browser. At least 2 packs with overlapping skill types available.

Task Sequence

Open the "Market Intel" pack. Note which skills are inside (names, types, grades).
Close the pack. Verify the close animation completes cleanly.
Open the "Domain Decks" pack. Note skills inside.
Close the pack.
Verify both packs now show their opened state visually.
Attempt to open both packs simultaneously (click one while another is open). Verify the app handles this gracefully: either queues the second open, prevents it with feedback, or transitions smoothly.
Navigate to /catalog. Search for a skill name seen in one of the opened packs. Verify the catalog search returns the expected skill.
Navigate back to /packs. Verify opened-pack state persists across navigation.

Acceptance Criteria

Opening and closing 3+ packs in sequence produces no stale state or stuck animations
Attempting to open a second pack while one is open does not crash or produce a blank screen
Opened-pack visual state persists across same-session navigation (packs → catalog → packs)
No memory leak observable after opening/closing 5+ packs (page remains responsive)

Non-Acceptance Signals

Page becomes sluggish after opening 3+ packs
Opened state resets when navigating away and back
Two drawers open simultaneously, overlapping
Animation state gets stuck (e.g., permanently in "closing-collapse" phase)

Evidence to Capture

Note: number of packs opened before any performance degradation
Screenshot showing multiple packs in opened state
Note: behavior when attempting to open a second pack while one is displayed

Tester Notes Prompt

"After browsing 3+ packs, did you feel you could compare skills across packs effectively? Was there anything that made comparing packs harder than it should be?"

Journey 4: Animation Performance Under Load (Persona A)

User goal: Verify animations run at 60fps with no jank on representative hardware
Trigger: QA pass before production deployment
Setup: Chrome DevTools Performance panel open. Test on: (1) modern desktop, (2) mid-range laptop with CPU throttling 4x, (3) mobile device or emulated mobile with CPU throttling 6x.

Task Sequence

Open Chrome DevTools Performance panel. Enable CPU throttling at 4x slowdown.
Start recording. Open a pack with the largest skill count (Foundation or Forge set).
Observe the fan-out animation in the performance trace. Check for long frames (>16.6ms).
Flip 3 cards in sequence while recording.
Close the pack and observe the close sequence in the trace.
Stop recording. Analyze the flame chart for layout thrashing, excessive paint, or JS long tasks during animations.
Repeat at 6x CPU throttle to simulate low-end mobile.

Acceptance Criteria

No animation frame exceeds 32ms (allowing one dropped frame) at 4x CPU throttle on desktop
Fan-out animation for packs with 10+ cards completes without visible stutter
Card flip animation maintains 30fps minimum at 6x CPU throttle
No layout thrashing (repeated forced reflow) during any animation phase
Total JS heap does not grow by more than 5MB after 5 open/close cycles

Non-Acceptance Signals

Visible jank during fan-out on a modern desktop without throttling
Performance trace shows forced synchronous layouts during animation
Memory grows monotonically with each open/close cycle (leak)

Evidence to Capture

Chrome Performance trace export (.json) for the full open → browse → close cycle at 4x throttle
Screenshot of flame chart highlighting longest frame during fan-out
Memory snapshot before and after 5 open/close cycles
Note: max frame duration observed at each throttle level

Tester Notes Prompt

"At what throttle level did the animations start to feel sluggish? Which specific animation phase was worst?"

4. Deck Builder Journeys

Note: No visual UX spec exists for the deck builder. These journeys test concept acceptance based on the Hearthstone-inspired description and VARD/ORD/AFPS deck metadata from the roadmap. Implementation details (layout, slot count, drag mechanics) are assumptions subject to the evidence gate above.

Journey 5: First Deck Creation (Persona C)

User goal: Build a custom workflow deck representing their preferred skill sequence
Trigger: Power user navigates to a "Deck Builder" or "Build a Deck" entry point from the packs or catalog page
Setup: Desktop browser. User has browsed at least 2 packs. 4 deck slots available: VARD, ORD, Business AFPS, Devtool AFPS.

Task Sequence

Find the deck builder entry point. Verify it is discoverable from the main navigation or the packs page (not hidden in a submenu or requiring a direct URL).
See the 4 available deck templates (VARD, ORD, Business AFPS, Devtool AFPS). Verify each has a name, a short description of its workflow purpose, and a visual theme.
Select the "Devtool AFPS" deck to start building.
Browse available skill cards in a sidebar or panel. Verify skills are filterable by pack, type, or search.
Drag a skill card from the available pool into the deck. Verify: drag feedback is visible (card follows cursor, drop zone highlights), the card snaps into a slot on drop.
Add 4 more skills to the deck (5 total). Verify the deck shows skills in the order they were added.
Reorder a skill by dragging it to a different position in the deck. Verify the reorder animation is smooth and the new order persists.
Remove a skill by dragging it out of the deck or using a remove affordance. Verify the slot empties and remaining skills reflow.
Verify the deck shows a workflow sequence indicator: arrows or connectors between skills showing the execution order.
Save the deck (or verify it auto-saves). Navigate away and return. Verify the deck contents persist.

Acceptance Criteria

Deck builder is reachable within 2 clicks from the homepage
All 4 deck templates are visible with names and descriptions
Drag-and-drop works for adding, reordering, and removing cards
Deck displays skills in sequence order with visual connectors
Deck state persists across page navigation (localStorage or equivalent)
Each deck can hold at least 8 skill cards
Duplicate skills in the same deck are prevented or flagged

Non-Acceptance Signals

No discoverable entry point to the deck builder from production pages
Drag-and-drop does not work (cards not draggable, no drop zones)
Deck state is lost on page refresh
No visual distinction between the 4 deck types
Skills can be added but not reordered
No visual feedback during drag (card disappears or doesn't follow cursor)

Evidence to Capture

Screen recording of full deck creation flow: browse → drag → drop → reorder → remove → save
Screenshot of completed deck with 5+ skills showing sequence order
Screenshot of deck after page reload (persistence check)
Note: time to build a 5-skill deck from scratch

Tester Notes Prompt

"Did the deck-building experience feel like composing a workflow, or just collecting cards into a list? Did the deck template themes (VARD, ORD, etc.) help you understand what kind of workflow you were building?"

Journey 6: Deck Workflow Validation (Persona C)

User goal: Verify that the deck's skill sequence represents a valid workflow chain
Trigger: Power user finishes building a deck and wants to validate it makes sense as a workflow
Setup: A deck with 5+ skills already built. Include at least one skill that would be out of sequence (e.g., /ship before /plan).

Task Sequence

View the completed deck. Look for workflow validation indicators (green checkmarks, warning icons, sequence arrows).
Deliberately place a skill out of canonical order (e.g., add /ship as the first skill, before any planning skill).
Check whether the deck builder shows a warning or suggestion about the out-of-order placement.
Correct the order. Verify the warning resolves.
Add a skill from a pack not associated with the deck's theme (e.g., a game pack skill in a Devtool AFPS deck). Check whether the deck builder flags or permits cross-pack skills.

Acceptance Criteria

Deck shows visual sequence indicators (arrows, numbers, or connectors between cards)
Out-of-order skills produce a visible warning (not a hard block — users can override)
Cross-pack skills are permitted but visually distinguished
Canonical chain order is documented or shown as a reference within the builder

Non-Acceptance Signals

No validation feedback whatsoever (deck is just an unordered collection)
Validation is so strict it blocks valid creative combinations
No visual reference for what the canonical chain looks like

Evidence to Capture

Screenshot of deck with out-of-order skill showing warning state
Screenshot of deck with cross-pack skill showing visual distinction
Note: was the validation helpful or annoying?

Tester Notes Prompt

"Did the validation help you understand the canonical workflow order, or did it feel like an arbitrary constraint? Would you want stricter or looser validation?"

5. Cross-Cutting Journeys

Journey 7: Homepage-to-Deck Full Funnel (Persona A)

User goal: Complete the full discovery-to-engagement funnel: land on homepage, explore packs, build a deck, understand the product value
Trigger: Developer arrives from GitHub README link
Setup: Fresh browser session. Desktop viewport. No prior visits.

Task Sequence

Land on homepage. Within the first viewport, identify what G Skillpacks is and what the primary action is.
Click the primary CTA. Verify it leads to an interactive experience (not a static page).
Open one pack. Read 2-3 cards. Close the pack.
Navigate to the deck builder (from nav or in-page link).
Build a small deck (3 skills). Verify the deck reflects what you browsed.
Navigate to /catalog. Search for a specific skill by name. Verify it appears.
Navigate to /follow. Verify the page has working links to GitHub, YouTube, Discord, LexCorp.
Return to the homepage. Verify the page state is consistent (opened packs still shown as opened).

Acceptance Criteria

Full funnel (homepage → packs → deck builder → catalog → follow → home) completes without errors
Page transitions between routes are fast (<300ms for Next.js client navigation)
No stale state: opened packs remain opened, deck contents persist
Tester can articulate what G Skillpacks is after completing the funnel
Back button navigation works correctly at every step

Non-Acceptance Signals

Homepage still shows the old static blueprint panel with no card pack elements
Navigation between routes causes full page reloads (migration incomplete)
State is lost during navigation (packs reset to sealed, deck empties)
Dead links or 404 pages in the flow

Evidence to Capture

Full-flow screen recording from homepage landing to return
Note: time to complete the full funnel
Note: any point where the tester felt confused or lost

Tester Notes Prompt

"After completing the full loop, could you explain to someone else what G Skillpacks is and why they might want it? What was the most compelling moment in the experience? What was the weakest?"

Journey 8: Accessibility & Reduced Motion (Persona B)

User goal: Navigate the full pack-opening experience using keyboard only and with reduced motion enabled
Trigger: Accessibility audit before production launch
Setup: Desktop browser. Enable prefers-reduced-motion: reduce in OS or DevTools. Disconnect mouse.

Task Sequence

Tab through the page. Verify all sealed packs are focusable and have visible focus indicators.
Press Enter or Space on a focused pack. Verify the pack opens (with reduced or no animation).
Tab through the revealed cards in the drawer. Verify each card is focusable.
Press Enter on a card. Verify it flips (with reduced or no animation).
Press Escape. Verify the drawer closes and focus returns to the pack that was opened.
Verify all animations are either eliminated or reduced to simple opacity/position transitions (no spring physics, no 3D transforms).
Enable a screen reader (VoiceOver on macOS, NVDA on Windows). Verify pack names, skill names, and state changes are announced.

Acceptance Criteria

All interactive elements are keyboard-reachable via Tab
Focus indicators are visible on every focusable element
Enter/Space opens packs, flips cards, and activates buttons
Escape closes the drawer and returns focus to the triggering element
prefers-reduced-motion eliminates spring physics and 3D transforms
Screen reader announces pack name when opened, skill name when card is focused, and "flipped"/"unflipped" state on card interaction
No content is only conveyed through animation (text fallbacks exist)

Non-Acceptance Signals

Packs cannot be opened via keyboard at all
Focus trap: keyboard user gets stuck inside the drawer with no escape
Reduced motion setting is ignored (full spring animations still play)
Screen reader announces nothing meaningful on pack open or card flip

Evidence to Capture

Screen recording of keyboard-only navigation through open → browse → flip → close
Screenshot of focus indicator on a sealed pack
Screenshot of reduced-motion state (what does the "open" look like without animation?)
Screen reader transcript or recording of announcements during pack interaction

Tester Notes Prompt

"Could you accomplish everything a mouse user can with keyboard alone? Did any interaction feel like it was designed only for mouse/touch?"

File	Action	Content
`research/uat-plan.md`	Create	Full UAT plan with 8 journeys, persona definitions, evidence sources, acceptance criteria, result log templates
`tasks/manual-todo.md`	Update `## UAT Journeys`	8 human-run journey checklist items referencing `research/uat-plan.md`
`alignment/uat-card-pack-migration.html`	Already written	This page

Surface	Journeys	Coverage
Card pack animations	J1 (desktop open/close), J2 (touch), J4 (performance)	Happy path, touch, perf profiling
Site migration	J3 (multi-pack), J7 (full funnel), J8 (a11y)	State persistence, cross-route nav, keyboard/screen reader
Deck builder	J5 (creation), J6 (validation)	Build flow, sequence validation, persistence
Cross-cutting	J7 (full funnel), J8 (a11y)	End-to-end flow, reduced motion, screen reader

UAT: Card Pack Migration + Deck Builder

1. Evidence & Source Coverage

Current Implementation State

Research Evidence Used

Evidence Gaps

2. Target User Personas

Persona A: Developer Evaluating Skillpacks

Persona B: Content Creator Browsing Collections

Persona C: Power User Building Workflow Decks

3. Card Pack Migration Journeys

Journey 1: First-Visit Pack Discovery (Persona A)

Task Sequence

Acceptance Criteria

Non-Acceptance Signals

Evidence to Capture

Tester Notes Prompt

Journey 2: Touch-Device Pack Interaction (Persona B)

Task Sequence

Acceptance Criteria

Non-Acceptance Signals

Evidence to Capture

Tester Notes Prompt

Journey 3: Multi-Pack Browse & Compare (Persona A)

Task Sequence

Acceptance Criteria

Non-Acceptance Signals

Evidence to Capture

Tester Notes Prompt

Journey 4: Animation Performance Under Load (Persona A)

Task Sequence

Acceptance Criteria

Non-Acceptance Signals

Evidence to Capture

Tester Notes Prompt

4. Deck Builder Journeys

Journey 5: First Deck Creation (Persona C)

Task Sequence

Acceptance Criteria

Non-Acceptance Signals

Evidence to Capture

Tester Notes Prompt

Journey 6: Deck Workflow Validation (Persona C)

Task Sequence

Acceptance Criteria

Non-Acceptance Signals

Evidence to Capture

Tester Notes Prompt

5. Cross-Cutting Journeys

Journey 7: Homepage-to-Deck Full Funnel (Persona A)

Task Sequence

Acceptance Criteria

Non-Acceptance Signals

Evidence to Capture

Tester Notes Prompt

Journey 8: Accessibility & Reduced Motion (Persona B)

Task Sequence

Acceptance Criteria

Non-Acceptance Signals

Evidence to Capture

Tester Notes Prompt

Explicit Non-Goals for This UAT

Compile Section