# Visual Design Contract
`AGENTS.md` is the canonical statement of the blank-canvas rule — check
`app/routes/_index.tsx` and `app/global.css`, preserve any real UI/brand
already there, and only treat the canvas as blank when those files still show
the starter's placeholder. This file does not restate that rule; it records
**this app's** visual direction. The fields below are the source of truth for
that direction: once filled in, read and preserve them on every build; while
they are still empty, the first substantial UI pass fills them in.
## Non-negotiable: impress by default
When this app is still a blank canvas, every app generated from this template
must look **spectacular on first load**, even when the build prompt gives no
design direction. "Looks like a clean, intentional product" is the floor, not
the goal. When no direction is supplied, you still commit to one — do not
default to safe gray SaaS:
- Commit to one concrete visual world (see the `frontend-design` skill and its
`references/visual-direction.md`). Do not ship the neutral placeholder theme.
- Choose a product-fitting accent family and set it in the `app/global.css`
tokens for **both** light and dark. Never leave the 0%-saturation default as
the shipped palette.
- Establish a clear type hierarchy, a consistent spacing rhythm, and one
signature detail (a considered empty state, a distinctive header, a crafted
primary action) that makes the surface feel designed for its domain.
- Get focus, hover, empty, loading, and dark-mode states right — that polish is
the difference between an AI demo and a product.
Pick a direction and execute it fully; never average toward generic SaaS. Once
a direction is established and recorded below, preserve and extend it rather
than starting over unless otherwise directed to.
## Fill in before building the first surface
Once the fields below are filled in, they describe this app's established
visual direction — read and preserve them on every subsequent build; do not
re-derive a new direction. The first UI pass must fill these fields in as
part of that build, not leave them as an empty template.
- Product mode: `experience`
- Audience and cadence: Thai moviegoers browsing independent cinemas; occasional discovery.
- Visual world (name + the feeling it creates): Dim indie screening room — friendly, warm, a little playful (pixel-style logo, rounded chips and cards).
- Palette family + neutral undertone: Cinema crimson (#8F0808 / #A92626 / #D47272) on near-black neutrals (#0D0D0D, #1B1B1B, #242424) with a slight warm cast.
- Type treatment: Inter + Noto Sans Thai; Jersey 15 pixel face for the AlterFlixHub wordmark only. เนื้อความยาว (บทความ/ย่อหน้าอ่านต่อเนื่อง เช่นหน้า /about) ใช้ `font-content` = IBM Plex Sans Thai Looped (มีหัว, 400/500) — หัวข้อและ UI ยังเป็น Inter + Noto Sans Thai ตามเดิม
- Composition: Full-bleed hero with crimson glow, centered glass search box, 4-column card grid at 1224px max.
- Shape language: Soft radii (8px controls, 18px pills, 16-20px cards), frosted-glass panels.
- Anti-references (defaults this app must not drift toward): Gray SaaS dashboards, light themes, neon gradients, heavy chrome.
## โลโก้ (ห้ามเปลี่ยนแปลง — ห้ามตีความใหม่)
สเปกนี้เป็นข้อบังคับ ใช้กับทุกหน้าและทุกภาษาที่รองรับ:
| หัวข้อ | ค่าที่กำหนด |
| -------------------- | -------------------------------------------------------------------------------- |
| คำ | `AlterFlixHub` — ตัวสะกด/ตัวพิมพ์นี้เท่านั้น (ไม่ ALL CAPS, ไม่เว้นวรรค, ไม่แปล) |
| ฟอนต์ | `Jersey 15` **เท่านั้น** ห้ามใช้ Inter หรือฟอนต์อื่นแทน |
| น้ำหนัก/สไตล์ | ตามฟอนต์ดั้งเดิม — ห้ามใส่ bold/italic/uppercase/letter-spacing/เงา/ไล่สี |
| สี | `#8F0808` เท่านั้น (ทุกสถานะ รวม hover/active) |
| ขนาด header (navbar) | `text-4xl` = **36px** |
| ขนาด footer | `text-2xl` = **24px** |
| ตำแหน่ง | header: element แรก ชิดซ้ายสุด และคลิกกลับหน้าแรกได้ · footer: ซ้ายสุดของแถว |
- ไม่อนุญาตให้เพิ่มขนาดที่สาม หรือเปลี่ยนสี/ฟอนต์แม้ในสถานะ hover/active
- ใช้ `Logo` เป็นข้อความแทนช่องรูปที่ยังไม่มีในแกลเลอรีหน้าโรงหนัง (`Gallery`) — ช่องหลัก `size="md"` (36px), ช่องย่อย `size="sm"` (24px) เท่านั้น; ข้อความ alt ยังใช้ `gallery.main/second/third` เพื่อการเข้าถึง
- การเปลี่ยนใด ๆ ต้องได้อนุมัติจากเจ้าของโปรเจกต์ก่อน แล้วอัปเดตพร้อมกันทั้งตารางนี้, `LOGO_SPEC` (`app/lib/design-tokens.ts`) และ `app/components/site/Logo.spec.ts`
- ตัวบังคับเชิงโค้ด: `Logo` อ่านค่าจาก `LOGO_SPEC` ผ่าน `logoClasses()` — ถ้ามีคนแก้สเปก เทสต์ `Logo.spec.ts` จะพังทันที
## Layout contract (บังคับ)
- หน้าเว็บจบที่ footer เสมอ: `SiteShell` เป็น `flex flex-col min-h-dvh` + เนื้อหาอยู่ใน `flex-1` (block ไม่ใช่ flex-col เพื่อไม่ให้ `main` ที่มี `mx-auto` หดเป็น max-content)
- ของตกแต่งพื้นหลัง (รูปฮีโร่, gradient, glow) ต้องอยู่ใน `BackdropFrame` = `absolute inset-0 overflow-hidden` เสมอ — ถ้าปล่อยเป็น absolute ลอย ๆ ที่ใช้ `top-[…px]`/`bottom` ค่าเยอะ ๆ จะยืด `scrollHeight` ให้ยาวเกินเนื้อหา ทำให้มีพื้นที่ว่างเลื่อนได้ใต้ footer
- แสงที่ต้องอยู่ช่วงล่างของหน้าให้ยึด `bottom-*` ไม่ใช่ `top-[px]` ตายตัว เพราะความสูงหน้าเปลี่ยนตามจำนวนการ์ดที่แสดง
## Motion contract (บังคับ)
- ทุกอนิเมชันใช้ **`transform` / `opacity` เท่านั้น** (ห้าม `width/height/top/left`) · ตัวแปร: `--fx-fast 160ms`, `--fx-base 280ms`, `--fx-page 460ms`, `--fx-slow 640ms`, `--fx-ease-out cubic-bezier(0.16,1,0.3,1)` · หน่วงต่อชิ้นไม่เกิน ~240ms
- **การเปิด/ปิดอนิเมชันมีสองชั้น — ต้องมีทั้งคู่**:
1. **สถานะ "ซ่อนก่อน reveal"** ผูกกับ `html.fx-motion [data-reveal]{opacity:0}` — คลาสนี้ใส่โดยสคริปต์ใน `