wangjia/pangolin
1
0
Fork 0
Code Issues Pull Requests 1 Actions 1 Packages Projects Releases 19 Wiki Activity
Files
main
pangolin/design/CLAUDE.md
T
wangjia 83fce75c8c docs(ds-flow): Phase 1.6-1.7 — ui_kits 标 DEPRECATED + 真源指针收敛 
用户定:ui_kits 暂留(整屏布局尚无 HTML 替代,重建属 L3 不在本轮),标废弃
不删。

- design/CLAUDE.md:顶部加「真源对照」横幅(令牌→prototype/tokens.css、原子
  →atoms.css+index.html、图标→icons.js、Flutter→client/lib/widgets、Web→
  web/*;colors_and_type.css 降级别名、design/flutter 已删、ui_kits DEPRECATED、
  _ds_manifest/_ds_bundle 历史派生物);§6「修改设计系统时」重写为 ds-flow 流程。
- design/ui_kits/DEPRECATED.md:醒目废弃标记 + 真源指引 + 暂留理由。
- 1.7:确认无构建/CI 消费 _ds_manifest/_ds_bundle/_adherence,登记职责交
  index.html,旧工具产物标历史派生物(不删,无消费者)。

Phase 1(原型单源三件套)完成。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-08 00:59:26 +08:00

14 KiB
Raw Permalink Blame History

CLAUDE.md — 穿山甲 VPN · Pangolin VPN 设计系统

本文件是项目持久指令,任何会话自动注入。目标:让任何 agent(含 Claude Code)都能完全还原这套设计,不走样。生产前端是 Flutter;React/HTML 是视觉规范参考。

⚠️ 真源对照(2026-07 ds-flow 治理后,以此为准;下文历史章节的旧路径逐步迁移中)

关注点 现在的真源 已废弃/降级
设计令牌 design/prototype/tokens.css(ds-flow 原型单源) colors_and_type.css 现为薄 @import 别名,勿在此加变量
组件原子 design/prototype/atoms.css + 登记页 design/prototype/index.html —
图标 design/prototype/icons.js(Lucide sprite 单源) —
Flutter 组件实现 client/lib/widgets/(canonical)+ client/lib/pangolin_theme.dart(实现层) design/flutter/ 已删除;本文下文 flutter/… 路径作废
官网/用户中心实现 web/website/ · web/usercenter/(各自 canonical) —
整屏视觉参考 design/ui_kits/(DEPRECATED · 仅历史整屏布局参考,勿当真源;整屏 HTML 化后退役) 旧 DS 工具 _ds_manifest.json/_ds_bundle.js 为历史派生物
详见根 CLAUDE.md「## 前端设计系统治理(ds-flow)」+ docs/frontend-ds-refactor-plan.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」。
  14. UI 组件只取自真相源:新增/修改任何 UI 组件,必须使用真相源里已定义的组件与令牌(colors_and_type.css + 本文件 §3/§5 + design/CONTRACT.md 组件清单)。真相源里没有的组件,先把规格补进真相源,再实现使用——绝不在业务代码里凭空造一套样式(如直接用 Material 默认外观)。新组件必须符合当前设计语言(暖大地色语义 token、大圆角、柔和暖阴影、明暗双主题自动适配)。

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-flow;以此为准,旧写法已废)

  • 改令牌 → 只改 design/prototype/tokens.css(原型单源),然后跑 codegen: node design/codegen/gen_flutter_tokens.mjs(生成 client/lib/pangolin_tokens.gen.dart,勿手改)+ cd web/{website,usercenter} && npm run gen:tokens。勿改 colors_and_type.css(它已是 @import 别名)。
  • 加/改组件原子 → 先在 design/prototype/atoms.css 定义 + design/prototype/index.html 登记页加展示卡(L1 无例外先原型),再落 canonical 实现:Flutter client/lib/widgets/、官网 web/website/、用户中心 web/usercenter/。
  • 加/改图标 → 先进 design/prototype/icons.js sprite,三端(Flutter/website/usercenter)只从此集取。
  • 评审原型:node design/prototype/serve.mjs → http://localhost:5180/(给 URL,不截图)。
  • 禁止再向 design/ 提交 Dart/TS 组件代码副本(会漂移;ui_kits/ 为历史 DEPRECATED 参考,勿新增)。
  • logo 改动 → 同步 SVG(design/assets/ + client/… 副本)+ Flutter pangolin_logo.dart + Web 内联 Mark。
  • 闸:改完跑 bash ci/check-codegen-drift.sh(codegen 零 diff)+ flutter analyze/flutter test(含 golden)。

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/官网内无任何支付表单,购买只引导到外部渠道
Reference in New Issue View Git Blame Copy Permalink