wangjia
a642bf16a2
design/ 同步自最新设计导出，新增 ui_kits/tablet/ 平板分栏布局；todo/ 录入 18 个并行实施任务。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
158 lines
12 KiB
Markdown
158 lines
12 KiB
Markdown
# CLAUDE.md — 穿山甲 VPN · Pangolin VPN 设计系统
|
||
|
||
> 本文件是项目持久指令,任何会话自动注入。目标:让任何 agent(含 Claude Code)都能**完全还原**这套设计,不走样。生产前端是 **Flutter**;React/HTML 是视觉规范参考。
|
||
|
||
---
|
||
|
||
## 0. 一句话定位
|
||
**穿山甲(Pangolin)** — 极简、轻量、亲和的跨平台消费级网络加速应用。暖大地色(穿山甲鳞甲)+ 大量留白 + 双语单显 + 深浅双主题。核心卖点:一键连接、智能选线、即开即用。
|
||
|
||
---
|
||
|
||
## 1. 不可动摇的设计铁律(违反即跑偏)
|
||
1. **颜色只用语义 token**(见 §3 / `colors_and_type.css` / `flutter/pangolin_theme.dart`)。绝不硬编码十六进制到组件里。
|
||
2. **暖色基调,拒绝纯黑纯白大面积填充**。浅色画布=沙米白 `--sand-50`;深色画布=暖 espresso `--sand-950`(非纯黑)。卡面浅色用纯白可,深色用 `#221E19`。
|
||
3. **主色是 clay 黏土铜 `#B96A3D`**,不是蓝/紫。绝不出现蓝紫渐变。渐变只在 clay 同色系内(`clay-600→clay-800`),且仅限 App 图标、PRO 套餐卡、连接成功光晕等少数强调处。
|
||
4. **圆角偏大**(按钮全胶囊 `full`,卡片 `lg–xl`,输入 `md`),传递亲和。
|
||
5. **阴影柔和暖调**(`rgba(45,30,20,…)`),绝不用冷灰阴影。
|
||
6. **单语言显示**:产品任一时刻只显示中文**或**英文,由设置/账户页「中文 / EN」段控切换。**绝不中英并排**(并排只出现在设计系统 specimen 卡)。
|
||
7. **状态用「色点 + 文字胶囊」**,绝不用 emoji。
|
||
8. **国家用 2 字母码块**(HK/JP/SG…),绝不用 emoji 国旗(跨平台渲染不一致)。
|
||
9. **图标用 Lucide 细线条**(2px stroke、圆角端点)。不用实心、不用 emoji、不用 Unicode 字符当图标。
|
||
10. **App 内不放支付表单**。资金流全走外部:兑换激活码 + 渠道(自助发卡店 / Telegram / LINE / 邮箱)。VPN 风控要求。
|
||
11. **品牌母题=行走穿山甲**(实心鳞甲剪影,朝右,圆头、匀称背、长尾)。**绝不手绘新图形或用 emoji 替代**——直接用 `assets/*.svg`。
|
||
12. **不堆砌**:无填充内容、无装饰性数字/图标、无 AI slop。留白即设计。
|
||
13. **脱敏(国内市场)**:产品主名统一「穿山甲 / Pangolin」,**不带 VPN 后缀**;定位话术=「网络加速 / 体验优化 + 隐私保护」。**红线词**(任何界面/宣传文案禁用):VPN、翻墙、科学上网、突破封锁、自由穿越、Go anywhere。安全词:加速、极速畅连、稳定、加速线路、隐私保护、无日志。「VPN」仅可出现在必要的技术文档/代码注释,绝不进 UI 文案、锁版、标题、aria-label。Logo 字标小字用「PANGOLIN」。
|
||
|
||
---
|
||
|
||
## 2. 字体系统
|
||
| 角色 | 字体 | 用途 |
|
||
|---|---|---|
|
||
| Display | **Sora**(600/700) | 标题、营销大字、Logo 字标 |
|
||
| Body/UI | **Manrope**(400–700) | 界面与正文主力 |
|
||
| CJK | **Noto Sans SC**(400/500/700) | 中文专用伴随字体 |
|
||
| Mono | **JetBrains Mono** | IP/速率/时长/密钥等数据(开 tabular nums) |
|
||
|
||
字阶:48 / 36 / 30 / 24 / 20 / 18 / 16 / 14 / 12。标题字距收紧 `-0.02em`,overline 放宽 `0.08em`。
|
||
> 四款均开源(Google Fonts),是本品牌**正式选定**字体,非临时替代。
|
||
|
||
---
|
||
|
||
## 3. 颜色语义 token(速查;完整见 `colors_and_type.css`)
|
||
**主色阶 clay**:50 `#FAF3ED` → 500 `#B96A3D`(品牌主色)→ 900 `#3D2213`
|
||
**中性 sand**:50 `#FAF8F4` → 900 `#1F1C18` → 950 `#14110E`(暗画布)
|
||
**语义**:success `#5B8C5A`(连接/安全)· warning `#D69A3C`(连接中)· danger `#C0533B`(断开/错误),各配 `*-subtle` 浅底。
|
||
|
||
语义变量(浅/深自动切换):`--bg` `--bg-subtle` `--surface` `--surface-2` · `--fg1/2/3` `--fg-on-accent` · `--accent` `--accent-hover/press/subtle/border` · `--border` `--border-strong` `--ring` · `--success/warning/danger(+ -subtle)`。
|
||
深色主题:`<html data-theme="dark">`;accent 在深色用 `clay-400`(更亮)。
|
||
|
||
间距 4px 基准:4/8/12/16/24/32/48/64。圆角:sm6/md10/lg14/xl20/2xl28/full。
|
||
动效:`ease-out cubic-bezier(.22,1,.36,1)`(进出场)· `ease-in-out`(状态)· 时长 fast140/base220/slow360。淡入+轻移,无浮夸弹跳。
|
||
|
||
交互态:hover 主色加深一档 / press 缩放 .97 + 再深 / focus clay 光环 `0 0 0 4px ring` / selected `accent-subtle` 底 + clay 字 / disabled sand-200 底 + sand-400 字。
|
||
|
||
---
|
||
|
||
## 4. 目录结构与职责
|
||
```
|
||
colors_and_type.css ← 唯一真相来源(CSS 令牌)
|
||
flutter/ ← 生产令牌 + 组件(Dart)
|
||
pangolin_theme.dart · 令牌 + 明/暗 ThemeData
|
||
pubspec.yaml · 工程清单模板(依赖+资产+字体)
|
||
main.dart · 入口示例(登录→引导→主框架)
|
||
assets/*.svg · 4 个矢量 logo
|
||
widgets/ · 组件 + 页面(见 §5)
|
||
README.md · Flutter 接入说明
|
||
assets/*.svg ← 品牌 logo(mark/white/mono/wordmark/app-icon)
|
||
preview/*.html ← 设计系统 specimen 卡(色彩/字体/间距/组件/品牌)
|
||
ui_kits/mobile/ ← 移动 App 视觉参考(React,可点击原型)
|
||
ui_kits/tablet/ ← iPad 客户端视觉参考(React,侧栏分栏布局)
|
||
ui_kits/desktop/ ← 桌面客户端视觉参考(React)
|
||
ui_kits/website/ ← 官网宣传页(产品/定价/下载/文档/Blog,响应式)
|
||
ui_kits/usercenter/ ← Web 用户中心(概览/订阅导入/兑换/邀请返利/设置含 2FA)
|
||
server/ARCHITECTURE.md ← 后端架构蓝本(Go 控制面 + WireGuard 数据面,供 Claude Code 实现)
|
||
README.md ← 品牌语境/内容/视觉/图标/索引
|
||
SKILL.md ← Agent Skill 入口
|
||
```
|
||
> 账户/设备管理已集成进移动+桌面客户端;**Web 用户中心**(`ui_kits/usercenter/`)职责为订阅分发 + 兑换 + 邀请裂变,服务 phase-1 网页闭环,不与客户端重复。
|
||
|
||
---
|
||
|
||
## 5. 还原产品时的页面清单(两端一致)
|
||
**移动 App**(`ui_kits/mobile/`,Flutter 见 `flutter/widgets/`):
|
||
- 登录/注册(`AuthFlow` / `auth_screen.dart`):登录=邮箱+密码;注册=邮箱→发验证码→填码→设密码(多端登录)
|
||
- 首次引导(`Onboarding` / `onboarding_screen.dart`):3 屏(连接全球→授权配置→安全无日志),可跳过
|
||
- 主框架 4 Tab(`home_shell.dart`):**连接 / 节点 / 统计 / 账户**;内容区支持**左右滑动切换 Tab**(>60px 且横向位移明显大于纵向,200ms 方向感知滑入;子页不响应)
|
||
- 连接:核心连接键三态(off 暖灰底+虚线轨道环 / connecting 旋转弧 / on 绿底+满环+计时)+ 当前节点卡 + 实时速率;**免费版额外显示额度卡**(今日剩余分钟 + 进度条(≤3 分钟变 warning 色)+ 「看广告开始使用」→ 点击后变绿色「已解锁 · 今日可用」)
|
||
- 节点:顶部置顶**「智能选择」推荐卡**(常驻 accent-subtle 底 + clay 渐变 zap 图标 + 「推荐」胶囊 + 文案「根据当前网络环境,自动选择最优节点」,默认选中);其下才是搜索 + 节点列表(国家码块·延迟·信号条·选中态)
|
||
- 统计:流量/延迟/时长指标卡 + 本周柱状图
|
||
- 账户:套餐横幅(免费版/PRO 自适应)+ 账户信息(邮箱/密码/退出)+ 设备管理 + 兑换/联系入口
|
||
- 账户子页(`account_screens.dart`):套餐选择 / 设备管理(可移除)/ 兑换&购买 / 联系我们
|
||
|
||
**桌面客户端**(`ui_kits/desktop/`):同上(含智能选择推荐卡与免费版额度卡),布局为 920×600 窗口 + 左侧栏导航(连接/节点/统计/账户/设置);登录为分屏卡(品牌左/表单右)。
|
||
|
||
**iPad 客户端**(`ui_kits/tablet/`):1180×820 横屏,左侧栏导航(触控尺寸,行高 ≥48px)+ 内容区;连接页为双栏(左大按钮 / 右信息列:额度卡→当前节点→速率);节点为双列网格 + 置顶智能推荐卡;复用 `ui_kits/mobile/parts.jsx` 的原子与字串。Flutter 端对应自适应断点:宽度 ≥900 时从底部 Tab 切换为侧栏布局。
|
||
|
||
**Web 用户中心**(`ui_kits/usercenter/`):概览(套餐状态/用量)· 订阅导入(订阅链接+二维码+一键导入三方客户端)· 兑换 · 邀请返利 · 设置(含 **2FA/TOTP 开关**,用户可自选开启)。响应式,移动端底部 Tab + 左右滑动切换。
|
||
|
||
**核心连接键**(最重要的组件,务必还原):圆形,三态——
|
||
- off:暖灰底 `sand-100` + clay power 图标 + 虚线轨道环 + 「点击连接」
|
||
- connecting:clay 实底 + 旋转进度弧 + 旋转 loader
|
||
- on:success 实底 + 白盾勾 + 满白环 + 圆内计时 + 「已加密」+ 绿光晕
|
||
> 注意:背景在渐变↔纯色间切换时,过渡只用 `box-shadow`/`background-color`,**不要 `transition: all`**(会导致背景计算失效)。
|
||
|
||
---
|
||
|
||
## 6. 修改设计系统时(本项目是 DS 工程)
|
||
- 改令牌 → 编辑 `colors_and_type.css` **同时**同步 `flutter/pangolin_theme.dart`(两者必须一致)。
|
||
- 改 specimen 卡 → `preview/*.html`,首行带 `<!-- @dsCard group="…" -->`。
|
||
- 改组件视觉 → 同步改 React(`ui_kits/`)与 Flutter(`flutter/widgets/`)两处。
|
||
- 改完跑 `check_design_system` 确认无报错(动效 token 标 `@kind other`)。
|
||
- logo 改动 → 同步 5 个 SVG(`assets/`)+ `flutter/assets/` 副本 + React 内联 `Mark`/`DMark` + Flutter `pangolin_logo.dart`。
|
||
|
||
---
|
||
|
||
## 7. 套餐口径(单一来源,所有界面/文案引用此处)
|
||
- **新用户体验期(7 天)**:注册即享 7 天免费使用(不限时长与节点)。
|
||
- **体验期后(免费版)**:仅 1 个基础节点;每日 10 分钟时长;**每日使用前需观看激励视频广告解锁**(流量不设上限,时长为唯一限制)。
|
||
- **PRO(付费)**:不限时长流量,80+ 加速线路,5 台设备。¥25/月(年付 ¥20/月)。
|
||
- **团队版**:¥99/月,10 席位。
|
||
- 收款渠道:自助发卡店 / **USDT (TRC20)** / Telegram / LINE / 邮箱。App 与官网内无支付表单。
|
||
|
||
## 8. 演示占位(落地需替换为真实信息)
|
||
渠道:自助发卡店 `shop.pangolin.vpn` · Telegram `@PangolinVPN_bot` · LINE `@pangolinvpn` · 邮箱 `support@pangolin.vpn` / `buy@pangolin.vpn`。账户演示 `me@pangolin.vpn`。服务时间「每日 9:00–24:00 (GMT+8)」。
|
||
|
||
---
|
||
|
||
## 9. 给 Claude Code 的实施工作步骤(从设计到产品)
|
||
|
||
> 总原则:**先读规范再动手;UI 以 `ui_kits/` React 原型为像素基准,逻辑以 `server/ARCHITECTURE.md` 为蓝本**。任何界面产出前,先打开对应 React 原型比对一遍。
|
||
|
||
### 第 0 步 · 进场必读(顺序固定)
|
||
1. 本文件 §1 铁律 → §7 套餐口径 → §5 页面清单。
|
||
2. `colors_and_type.css`(令牌真相源)与 `flutter/pangolin_theme.dart`(Dart 镜像)。
|
||
3. 目标端的 UI Kit 源码(如做移动端就读 `ui_kits/mobile/*.jsx`)。
|
||
|
||
### 第 1 步 · Flutter 客户端(主路径)
|
||
1. 新建工程,用 `flutter/pubspec.yaml` 覆盖;拷 `pangolin_theme.dart`、`widgets/`、`main.dart` 到 `lib/`,`flutter/assets/*.svg` 到工程 assets。
|
||
2. 字体:下载 Sora / Manrope / Noto Sans SC / JetBrains Mono 的 ttf 放 `fonts/`(族名对齐 pubspec),或改用 `google_fonts`。
|
||
3. `flutter pub get && flutter run` —— `main.dart` 已串好登录→引导→主框架,应能直接跑出演示态。
|
||
4. 对照 `ui_kits/mobile/` 逐屏补齐 Flutter 端差异(智能选择推荐卡、免费额度卡+看广告解锁、Tab 滑动切换)——React 原型是验收标准。
|
||
5. 接口对接前全部用演示数据;接口就绪后按 `server/ARCHITECTURE.md` §3 的契约替换。
|
||
|
||
### 第 2 步 · 后端(Go)
|
||
按 `server/ARCHITECTURE.md` §7 的模块顺序实现(openapi → auth → codes → devices → nodes → usage → 管理端)。每模块完成定义:单测 + OpenAPI 同步 + 错误文案双语且符合铁律 13 脱敏口径。
|
||
|
||
### 第 3 步 · 官网与用户中心(Web)
|
||
- 官网:以 `ui_kits/website/` 为样板迁移到静态框架(Astro/Next 皆可),保留 i18n 双语单显、响应式断点与全部脱敏文案。
|
||
- 用户中心:以 `ui_kits/usercenter/` 为样板,接 `server/` 的 me/redeem/devices 接口;2FA 用 TOTP。
|
||
|
||
### 第 4 步 · 验收检查清单(每个界面提交前自查)
|
||
- [ ] 颜色全部来自语义 token,无硬编码十六进制
|
||
- [ ] 明/暗两主题均验证过;中/英两语言均验证过(单显不并排)
|
||
- [ ] 文案无铁律 13 红线词;套餐数字与 §7 一致
|
||
- [ ] 图标只用 Lucide;国家码块无 emoji 国旗;状态胶囊无 emoji
|
||
- [ ] 连接键三态、智能选择默认选中、免费版额度/广告解锁流程与 React 原型一致
|
||
- [ ] App/官网内无任何支付表单,购买只引导到外部渠道
|