# Visual Design Language for Eryao Flutter App

This document defines the **visual design language** for `觅爻签问` under `apps/**`.
It is derived from:

- the existing product visuals in `old/app/**`
- the structure and quality bar of `social-app/apps/rules/visual_design_language.md`

It is the source of truth for visual consistency, surface hierarchy, and interaction tone.

---

## 0) Scope and Role (MUST)

- Applies to all Flutter UI work in `apps/**`.
- Defines visual intent, not business logic.
- If implementation constraints conflict with visual intent, keep the stricter implementation rule and preserve visual intent as much as possible.

---

## 1) Product Design Goal (MUST)

`觅爻签问` is a divination assistant app with Chinese cultural context.

The UI must feel:

- calm
- trustworthy
- warm-tech
- clear
- ceremonial but not mystical noise
- modern mobile-native

Avoid:

- enterprise admin panel aesthetics
- hyper-playful toy style
- over-dark cyber style
- ornamental visual clutter

---

## 2) Core Style Direction (MUST)

Primary style blend:

- **purple-centered brand palette** from old app
- **soft gray background field**
- **white card surfaces with rounded corners**
- **gradient hero card for primary action**
- **compact tag system for category/sign states**

Visual tone:

- soft, layered, readable
- lightweight but premium
- expressive in key actions, restrained elsewhere

---

## 3) Brand Palette (MUST)

Canonical colors extracted from old app:

- Primary Purple: `#673AB7`
- Accent Purple: `#9C27B0`
- Light Purple Surface: `#F0E6FF`
- Background Gray: `#F8F8F8`
- Text Dark: `#333333`
- Text Medium: `#666666`
- Text Light: `#999999`

Tag/status support colors:

- Gold result: bg `#FFF8E1`, text `#FFB300`
- Blue tag: bg `#E6F7FF`, text `#1890FF`
- Gray result: bg `#F5F5F5`, text `#9E9E9E`
- Warning: `#F57C00`

All UI usage should go through `ColorScheme` and `AppColorPalette` extension.

---

## 4) Surface Hierarchy (MUST)

Every screen should read in this order:

1. soft background field (`BackgroundGray` semantic slot)
2. core card modules (white rounded surfaces)
3. prominent primary-action hero card (purple gradient)
4. compact metadata chips (category/gua/sign)
5. subtle transient feedback (toast/snackbar)

Do not rely on color alone; use spacing, corner radius, and elevation to express hierarchy.

---

## 5) Shape and Spacing Language (MUST)

- Rounded geometry is default.
- Primary card radius: `16dp`.
- Secondary card radius: `12dp`.
- Input/button radius: `8dp`.
- Spacing rhythm follows `4/8/12/16/24/32`.
- Preserve generous vertical breathing room on login and home.

---

## 6) Typography and Tone (MUST)

- Headline: strong, concise.
- Body: readable and neutral.
- Caption/meta: low emphasis but still legible.
- Chinese copy should remain culturally natural and non-gimmicky.
- English copy should be concise, product-appropriate, and semantically aligned.

---

## 7) Page-Level Guidance (MUST)

### Login

- Top-left welcome title + subtitle.
- Phone input and code input row with fixed-width code button.
- Primary full-width login button.
- Agreement checkbox with inline clickable legal links.
- Bottom filing/registration text centered.

### Home

- Top greeting on the left, notification icon on the right with red-dot state.
- Gradient hero card with icon, title, subtitle, and main CTA.
- History section title + “more” entry.
- Vertical list of rounded history cards with compact status tags.
- Bottom nav: Home, center logo, Profile.
- First-entry modal: long welcome text requiring scroll-to-bottom confirmation.

---

## 8) Interaction and Motion (SHOULD)

- Keep transitions subtle and quick.
- Avoid heavy animation chains.
- Primary actions provide immediate feedback.
- Disabled states must be visually clear.

---

## 9) Accessibility and Internationalization (MUST)

- Support at least `zh` and `en`.
- Keep text scalable without overlap in critical controls.
- Ensure interactive targets are easy to tap.
- Contrast should remain readable on all key text/surface combinations.

---

## 10) Android Continuity Requirements (MUST)

To avoid losing local tokens/settings during upgrades:

- Keep stable `applicationId` across releases.
- Keep release signing keystore stable per channel.
- Persist token/session in local key-value storage.
- Keep backup/data-extraction rules explicit for shared preferences.

These are release continuity requirements and must be checked before each Android release.