eryao/apps/rules/visual_design_language.md

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.