@AGENTS.md

# Visit Syria: Frontend

English homepage (and future pages) for the Visit Syria tourism site. Laravel API lives in `../backend`; it is not wired in yet, content is static in `src/data/content.ts`.

## Stack and commands

- Next.js (App Router, TypeScript), React, `motion` (import from `motion/react`), `lenis`, plain CSS tokens in `src/app/globals.css` (no Tailwind).
- Fonts: `next/font/google` (Bricolage Grotesque display, Alexandria Arabic display, Readex Pro body). Icons: `@fontsource-variable/material-symbols-outlined` via the `<Icon>` component.
- `npm run dev` (use `-p 3100` if 3000 is taken), `npx tsc --noEmit`, `npm run build`.
- Run shell commands with `python`/Write-tool files when a heredoc contains apostrophes; the Bash tool's parser chokes on them.

## Source of truth for design

1. `Syria Design System v6.dc.html`: tokens, type, radii, components, motion (150/250/400ms, `cubic-bezier(.2,.7,.2,1)`), accessibility rules. Do not invent a competing system.
2. `Website UI kit (desktop).html`: page/section structure for the desktop site. It is a bundled page; to read it, open it in headless Chrome (puppeteer-core + `C:/Program Files/Google/Chrome/Application/chrome.exe`) and dump `document.body.innerText` and screenshots.

Tokens: cream `#FFF9F3` page, plum ink `#2A1B3D` text, rose `#C92A62` actions, blush `#FDE7EF`, violet `#5B3FD9` (offers only), sand `#F1E6DD` lines. Radii 6/12/20/28/pill. Only three elevation levels. Photography first: text sits under images on cards, never over them (the hero is the one exception).

## Skills to keep using

Invoke via the Skill tool before doing UI work; do not mention them in the UI or docs.

| Skill | Use it for |
| --- | --- |
| `design-taste-frontend` | Design decisions, anti-slop rules: declare a one-line design read and dials first (this project: variance ~7, motion ~7, density ~3). Hero max 4 text elements, no decorative dots/pills on images, eyebrows rationed, zero em-dashes in visible copy, one accent, CTA labels one per intent. The design system wins wherever it conflicts (cream palette, eyebrows, the requested scroll cue). |
| `emil-design-eng` | Motion craft: strong ease-out curves, no `scale(0)` entries, `:active` scale 0.97, enter under ~300ms for UI, exit faster than enter, stagger 30-80ms for UI (cinematic hero intro can be slower), gate hover behind `(hover: hover) and (pointer: fine)`, transform/opacity only, reduced motion respected. |
| `animate` / `review-animations` | Building or critiquing individual animations when asked. |
| `ui-ux-pro-max:ui-ux-pro-max` | Optional lookup for palettes/type/UX guidelines; never override the design system with it. |
| `mobile-native` | Mobile fixes (100dvh, tap highlight, sticky hover, notch). |

## Connectors / tools

- **Claude in Chrome** (`mcp__claude-in-chrome__*`): real-browser testing. Load tools with one `ToolSearch select:` call, start with `tabs_context_mcp`. It was not connected in the last session; fallback is headless Chrome via `puppeteer-core` (installed in the session scratchpad; reinstall with `npm i puppeteer-core` there, never in the project) taking screenshots at 1440x900 and 390x844 and checking `scrollWidth` vs `innerWidth`.
- **Motion connector** (`mcp__claude_ai_Motion__authenticate`): requested for the intro sequence but unauthenticated so far. Run authenticate, then use it for intro motion; until then the intro is hand-built with `motion/react` in `src/components/Hero.tsx`.
- **Higgsfield** (`mcp__claude_ai_higgsfield__*`): optional generation of stand-in hero video/photos. Costs the user credits, so ask before generating.
- **Artifact / Claude Docs**: only if the user asks for a shareable page or doc.

## Architecture notes

- Folders: `src/app/(site)/` holds public pages and wraps them in `SiteShell` (navbar + `<main>` + footer) via its layout; a new page is just `src/app/(site)/<route>/page.tsx`. `src/components/{layout,ui,providers}` are shared, `src/components/<page>/` holds page sections (`home/` today), `src/styles/{tokens,base,ui}.css` + `layout/` + `<page>/` are imported from `globals.css`, `src/data/{navigation,home}.ts` hold content (add `<page>.ts` per page).
- Navigation lives only in `src/data/navigation.ts` (navbar, mega panel, mobile accordion, footer all read it). Routes it points to are not built yet and fall through to `not-found.tsx` ("coming soon").
- Navbar is transparent only on `/` over the hero; every other route gets the solid bar. The home page composes `Hero` + the `.sheet` of sections; the hero is `position: sticky` and the cream `.sheet` slides over it.
- Media slots: `src/config/media.ts` (hero video/poster, destinations, experiences, about, group trip, stays, restaurants). `null` renders the design system's striped placeholder via `<Photo>`; set a path under `public/media/` to use real media.
- Hero intro timings live in `INTRO` in `Hero.tsx`: media clip reveal, nav, headline words, subtitle, search + chips, caption/scroll cue.
- Lenis (`SmoothScroll.tsx`) owns page scroll; use Motion `useScroll`/`useTransform` for scroll-linked effects, never `window.addEventListener("scroll")`.
- Section spacing uses `--sec`; adjacent cream sections halve their shared padding. Keep new sections on that variable to avoid dead white space.
- Client components only where needed (motion, state); `Footer`, `Photo`, `Icon`, data files stay server-safe.

## Rules of thumb

- Every animation needs a stated purpose; honor `prefers-reduced-motion` (Motion `useReducedMotion`, CSS media query).
- Layout is responsive by design, not shrunk: check 1440, 1024, 768 and 390 widths, no horizontal scroll.
- Use logical spacing so the Arabic/RTL version can follow (`dir="rtl"`, Alexandria display, +20% line-height, mirrored directional icons only).
- Not built yet: Arabic/RTL pages, API integration, real search, language switch, map page, inner pages.