eryao/.trellis/spec/web/index.md

Web Development Guidelines

Astro 6 + React 19 + Tailwind CSS 4 + shadcn/ui

---

Tech Stack

Layer	Technology	Version
Framework	Astro	6.x
Interactive UI	React	19.x (client-only, no RSC)
Styling	Tailwind CSS	4.x (via @tailwindcss/vite)
Component Library	shadcn/ui	latest
Language	TypeScript	5.x (strict)
i18n	Built-in (type-safe object in src/i18n/utils.ts)	-
Markdown Rendering	marked	latest
Auth	Supabase Auth JS SDK	-

Architecture Decision

• Astro SSG for marketing/public pages (SEO-critical)
• React client islands for interactive parts (Login, Dashboard, Notifications)
• No React Server Components — CVE-2025-55182 risk eliminated
• No Next.js — multiple critical CVEs (CVE-2025-55182, CVE-2025-29927, CVE-2025-66478)

Actual Dependencies

astro, @astrojs/react, react, react-dom, @tailwindcss/vite, tailwindcss, marked

---

Pre-Development Checklist

Before writing web code, read:

• This index
• Design file: web/design/eryao.pen
• Backend API contracts: docs/protocols/
• Error code mapping: docs/protocols/common/http-error-codes.md
• Mobile i18n files (for translation sync): apps/lib/l10n/app_*.arb

---

Project Structure

web/
├── design/                    # Pencil design files (.pen)
│   ├── eryao.pen
│   └── assets/                # Shared assets (images, legal)
│       ├── images/
│       └── legal/{zh,zh_Hant,en}/
├── public/
│   ├── images -> ../design/assets/images    # symlink, no duplication
│   ├── legal -> ../design/assets/legal      # symlink, no duplication
│   ├── favicon.ico
│   └── favicon.svg
├── src/
│   ├── components/
│   │   ├── Navbar.astro       # Marketing nav (responsive, lang switcher)
│   │   ├── Footer.astro       # Marketing footer (responsive)
│   │   ├── Hero.astro         # Landing hero section
│   │   ├── Showcase.astro     # Landing showcase section
│   │   ├── Testimonials.astro # Landing testimonials section
│   │   ├── CtaSection.astro   # Landing CTA section
│   │   ├── FeaturesPage.astro # Features grid page
│   │   ├── PricingPage.astro  # Pricing cards page
│   │   ├── AboutPage.astro    # About + company info page
│   │   └── LegalPage.astro    # Markdown legal page (generic)
│   ├── layouts/
│   │   └── Marketing.astro    # Nav + content + footer + scroll animations
│   ├── pages/
│   │   ├── index.astro        # Root redirect -> /zh/
│   │   ├── {zh,zh_Hant,en}/
│   │   │   ├── index.astro    # Landing
│   │   │   ├── features.astro
│   │   │   ├── pricing.astro
│   │   │   ├── about.astro
│   │   │   ├── privacy.astro
│   │   │   └── terms.astro
│   ├── i18n/
│   │   └── utils.ts           # Type-safe translations (all inline)
│   └── styles/
│       ├── global.css          # Tailwind entry
│       └── animations.css      # Scroll reveal animations
├── astro.config.mjs
├── tsconfig.json
└── package.json

---

Responsive Layout

All pages must be fully responsive: full-width sections, no fixed pixel widths.

Layout Principles

1. Full-width sections — Each section spans w-full, content is centered with max-w-7xl mx-auto
2. No fixed pixel widths — Use w-full, max-w-*, and flex/grid for all layouts
3. Mobile-first — Base styles target mobile, md: breakpoint for desktop
4. Viewport-filling sections — Hero and CTA use min-h-screen or generous padding to fill viewport
5. Smooth scroll transitions — Each section flows into the next with gradients or color changes

Breakpoints

Breakpoint	Target
Base (< 768px)	Mobile phones
md: (>= 768px)	Tablets and desktop

Section Patterns

Hero:       w-full, min-h-screen, bg-gradient, centered content
Showcase:   w-full, flex-col md:flex-row, gap, centered max-w
Testimonials: w-full, bg-slate-900, grid cols-1 md:cols-3
CTA:        w-full, bg-violet-600, centered
Footer:     w-full, bg-slate-950, responsive flex

---

Design Tokens

All colors from design map directly to Tailwind defaults:

Token	Tailwind	Hex
Primary	violet-600	#7C3AED
Primary light	violet-100	—
Background	white	#FFFFFF
Surface	slate-50	#F8FAFC
Dark bg	slate-900	#0F172A
Footer bg	slate-950	#020617
Border	slate-200	#E2E8F0
Warning bg	amber-50	#FFFBEB
Gradient top	white -> violet-50	—

---

Scroll Animations

Defined in src/styles/animations.css, triggered by IntersectionObserver in Marketing.astro.

Class	Effect	Use Case
.reveal	Fade up (translateY 24px)	Default for most elements
.reveal-left	Slide from left	Showcase left column
.reveal-right	Slide from right	Showcase right column
.reveal-scale	Scale in (0.95 -> 1)	CTA section
.stagger-1 to .stagger-4	Delay 0.1s-0.4s	Grouped elements (cards, grid items)

• All animations: 0.6-0.7s, cubic-bezier(0.22, 1, 0.36, 1) (ease-out-quint)
• prefers-reduced-motion: reduce disables all animations
• Observer rootMargin: 0px 0px -60px 0px for pre-trigger
• Elements are opacity: 0 until .visible class is added, then animation-fill-mode: forwards

---

i18n (CRITICAL)

Every user-visible text must use i18n keys. No hardcoded strings.

Supported Locales

Code	Language	Brand Name
zh	简体中文	觅爻签问
zh_Hant	繁體中文	覓爻簽問
en	English	MeiYao Divination

Implementation

• All translations are in src/i18n/utils.ts as a typed Record<Locale, Translations> object
• Access via t(locale, 'section') which returns the section object (e.g., t(locale, 'nav').features)
• URL strategy: /{locale}/path prefix (e.g., /zh/, /en/)
• Default locale: zh, root / redirects to /zh/
• Config in astro.config.mjs with prefixDefaultLocale: true

Rules

1. All text must come from t() — never inline strings
2. Brand name is always from footer.brandName (consistent across Navbar/Footer)
3. Check Flutter i18n first (apps/lib/l10n/app_*.arb) before inventing translations
4. Legal content loaded from public/legal/{locale}/ markdown files

---

Assets

• Shared assets live in web/design/assets/ (used by Pencil)
• web/public/images and web/public/legal are symlinks to ../design/assets/*
• Never duplicate assets — always use symlinks or references

---

Cross-Layer Contracts

API Integration

• Backend: FastAPI REST endpoints (see docs/protocols/)
• Auth: Supabase Auth JS SDK (client-side)
• Error format: RFC 7807 ApiProblem (same as mobile)

Brand Consistency (Flutter app)

• App title: "觅爻签问" / "MeiYao Divination" (NOT "MiYao")
• Company: 洵觅科技（深圳）有限公司 / Xunmee Technology (Shenzhen) Co., Ltd.
• Contact: xuyunlong@xunmee.com
• ICP: 粤ICP备2025428416号-1A

---

Quality Rules

Forbidden

• Do not use React Server Components (RSC)
• Do not import server-only modules in client islands
• Do not hardcode colors outside Tailwind tokens
• Do not use fixed pixel widths for layout (use responsive utilities)
• Do not use any in TypeScript
• Do not use third-party shadcn registries (official only)
• Do not duplicate assets — use symlinks

Required

• All pages must be fully responsive (mobile + desktop)
• All sections must be full-width with centered content
• All pages must pass Lighthouse SEO >= 95 (marketing pages)
• All interactive components must be accessible (ARIA)
• npm audit must be clean before merge
• TypeScript strict mode enabled
• prefers-reduced-motion must disable animations