# TrueTraceShorts website companion screen UX

Use this when adding a new AutoShorts/TrueTraceShorts video to the static website or polishing the companion-page/homepage visuals.

## User-corrected UX rules

- The website visual should show the scam screen directly in the same vertical 9:16 language as the short: phone, laptop, invoice, login page, popup, review section, payment request, etc.
- The detail-page `Example screen` must not crop a vertical short into a wide card. Display `screenImage` as a real 9:16 frame (`aspect-ratio: 9 / 16`) and verify dimensions in the browser.
- Prefer a strong opening/keyframe image from the actual video when it is instantly understandable and has no subtitles.
- If the first extracted frame is blank, transitional, cropped, subtitle-covered, or semantically weak, use a representative clean AI keyframe from the render package or generate a separate direct screen image with the image LLM; store it as `screenImage` with `screenImageAlt`.
- For video backgrounds/keyframes, avoid slipping back to hand-built/deterministic-looking graphics unless the renderer-owned semantic layer is intentionally minimal. The user explicitly prefers well-prompted premium AI images for professional-looking scenes, with deterministic UI/text only where needed for safety/control.
- After replacing deterministic graphics with AI images, remap scene order and durations against the voice/script segments. Pretty backgrounds that do not match the current voiceover/text are a failure even if they look premium. Use more keyframes if needed so each spoken beat has a matching visual state.
- Avoid artificial explanatory mock panels such as `Visible screen / The red flag / Notice → Move safely / Safer move` when they look like a constructed diagram rather than the real screen.
- Avoid odd production labels in public UI: `Start frame`, `Video start image`, `Use this visual hook first`. Use visitor language such as `Example screen`, or omit the badge entirely.
- Keep text below images or in separate cards. Do not overlay descriptive text on the scam image if it covers the hook.
- Companion checklists should feel like a useful printable decision aid, not a cheap download. Do not add `.txt` checklist downloads for this user; use `Save as PDF` / browser print and topic-specific checklist details instead.
- When the topic warrants more than short bullets, include `checklistDetails[]` with `title`, `why`, and `safer` fields. Build the Astro site after generation; malformed YAML such as missing spacing around an empty array (`checklistDetails:[]`) can break content sync.

## Homepage carousel pattern

For the `Common screens` homepage block:

- Show three cards on desktop.
- Support swipe/trackpad, but also visible mouse buttons for previous/next.
- Allow mouse-wheel scrolling inside the carousel when useful.
- Each card should show the image first, then category/title/short visible-screen text below.
- The card should link to the companion guide.

## Handoff metadata

Candidate/spec fields to preserve:

```json
{
  "thumbnail": "/redflags/thumbnails/<slug>-start.webp",
  "screenImage": "/redflags/thumbnails/<slug>-start.webp",
  "screenImageAlt": "Direct view of the suspicious screen...",
  "visualBrief": "Direct close-up view of the suspicious screen on phone/laptop..."
}
```

`visualBrief` should explicitly say:

- direct screen view;
- what specific scam visual must be visible;
- no real brands/domains/phone numbers/bank data/QR codes;
- no abstract cyber graphics;
- keep critical UI text example-only or renderer-owned.

## Verification

After generating a companion page:

1. Re-run the companion generator with the saved candidate JSON and final media-cache video path, usually with `--force`, even if the render package already says the website companion was created. This makes the public content/thumbnail deterministic from the latest approved artifact.
2. Run the website build.
3. Check `/`, `/redflags/`, and `/redflags/<slug>/` return 200 against the built static output.
4. Browser-QA the detail page and homepage carousel.
5. Verify there are no console errors.
6. Confirm the newest guide appears first if homepage sorting uses `lastUpdated`.
7. If the live custom domain cannot be resolved or reached from the agent environment, do not claim live deployment succeeded. Report the local build/smoke/browser results plus git push status separately, and label the live-domain check as inconclusive.