Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
Cindy 手机版设计指南
状态:权威设计规范。新增 / 修改任何 UI 前先读本文。 定位:这是
docs/design-rules/cindy-design-system.md的轻量移动版——共享 Cindy 品牌与业务语义,但不照搬桌面的 ColorRegistry 重型架构。手机端用一套 light/dark 双色板 + 收敛阶梯 + RN 主题 hook。 色值由移动端独立决定(2026-09-26 起为「象牙白」色板,见DESIGN.md §15.13):语义与桌面一一对应,具体色阶、对比度与暖度不与桌面同步。
1. 视觉哲学
承接桌面:灰度为主、默认零阴影、pill 几何、字重克制。在此之上叠加移动端约束:
- iOS 优先,触控优先,跟随系统 light / dark 自动切换(
useColorScheme)。 - 灰度环境:除品牌 teal(就绪态)、Heart Orange(运行/thinking 态)和已登记的 Beta 渠道红色状态徽标外,界面全是黑白之间的灰阶。不引入任何品牌蓝 / 绿 / 红等装饰色。
- 唯一的个性化例外:用户在设置里主动选择的「我的消息气泡颜色」,只染用户自己的消息气泡,默认仍是灰阶;规则见根规范
DESIGN.md「Personal message bubble colors」。 - 模型选择器的账号额度条沿用桌面语义:剩余 ≥30% 用
textSecondary,10% < 剩余 <30% 用quotaBarWarn,剩余 ≤10% 用quotaBarCrit。额度专用语义在根规范DESIGN.md§2 / §10 登记,不借用房主皇冠或任务错误 token。颜色只用于额度条,百分比文字继续保留;iOS / Android 共用真实比例绘制,不设置最小填充长度,0% 留空。
- 唯一的个性化例外:用户在设置里主动选择的「我的消息气泡颜色」,只染用户自己的消息气泡,默认仍是灰阶;规则见根规范
- 圆角走四档阶梯(与
src/theme/tokens.ts的radius一致,守护测试拦截阶梯外值):micro(4,缩略图内 chip、勾选指示器等微元素)/control(8,卡片内层控件)/container(12,卡片 / 容器)/pill(9999,交互元素)。禁止阶梯外中间值(0 / 3 / 6 / 28 等)与字面量圆角。根规范docs/design-rules/DESIGN.md§5 的三档制约束的是桌面 surface;其「Mobile」节明确把 §15.13 / §16 之外的 mobile 布局细节委托给apps/mobile的实现,mobile 圆角阶梯以tokens.ts为准。 - 默认零阴影:层次靠背景色差 + 1px 边框。2026-09-27 用户明确要求的局部例外:首页主菜单抽屉(含伙伴入口)用右侧容器圆角与柔和投影,颜色走 homeDrawerShadow,外壳承载阴影、内层裁切内容;不扩展到页面卡片或任务列表侧栏,见 DESIGN.md §6。
- 字重克制:按角色用 400 / 500 / 600(见 §3「字重与字色按角色搭配」)。UI chrome 无 700+。唯一例外是根规范
docs/design-rules/DESIGN.md§3「排版豁免登记表」已登记的域——原生 Markdown strong(src/session/MessageRenderer.tsx的markdownStrong→fontWeight.bold)与登录品牌画布(app/(auth)/login.tsx、src/components/LoginSkinControls.tsx、src/auth/loginSkinLayout.ts)。这些是用户内容语义与品牌画布,不算 chrome;chrome 本身的上限仍是 600。 - 手机只做减法(详见
mobile-current-execution-plan.md):主层信息量不超过桌面主层;视觉轻、触控够(可见图标小,hitSlop 补足热区)。
2. 颜色 token
颜色分两层:随主题切换的 ThemeColors 与主题无关的不变量。组件永远写 token,不写 hex(写死 hex 的组件在 dark 下不会变色)。
源:src/theme/tokens.ts(lightColors / darkColors / palettes)。
浅色为象牙白(页面、卡片、描边带一点暖,正文中性),深色为纯中性近黑(2026-09-26 用户定稿)。下表是常用的底色 / 文字 / 描边;完整清单以 tokens.ts 为准,移动端专用层见 DESIGN.md §15.13。
| token | light | dark | 用途 |
|---|---|---|---|
surface |
#F9F9F6 |
#121212 |
页面背景 |
surfaceElevated |
#FFFFFC |
#1E1E1E |
抬一层:Card / 弹窗 / 输入框 |
surfaceListRow |
#FFFFFC |
#1E1E1E |
列表行 |
surfaceTranslucent |
rgba(249,249,246,.78) | rgba(18,18,18,.78) | 吸顶栏半透明 |
surfaceChip |
#EAEAE6 |
#2A2A2A |
chip / pill / 选中行填充 |
border |
#CCCCC8 |
#383838 |
1px 分隔线 / 边框 |
borderTranslucent |
rgba(204,204,200,.62) | rgba(56,56,56,.62) | 半透明边框 |
borderStrong |
#858581 |
#8A8A8A |
强调边框 / 次要图标点(≥ 3:1) |
textPrimary |
#0F0F0F |
#EDEDED |
主标题 / 主正文 |
textSecondary |
#4D4D4A |
#BDBDBD |
次要文字 / 多数图标 |
textTertiary |
#686864 |
#999999 |
三级文字 / 时间、计数等 metadata |
textPlaceholder |
#858581 |
#757575 |
仅限输入框占位字与同源的语音态提示(≈3.5:1,低于 4.5:1 的登记例外) |
cta |
#0F0F0F |
#EDEDED |
主操作填充(dark 反相为近白) |
ctaText |
#FFFFFF |
#121212 |
CTA 上的文字 |
homeListFab |
#0F0F0F |
#E6E6E6 |
素雅新建对话 FAB:dark 比 cta 略收,避免主入口在深底上过跳 |
statusReady |
#19D2C1 |
#19D2C1 |
就绪 / 在线点(品牌 teal,语义不变) |
statusAccent |
#EA6B17 |
#EA6B17 |
运行 / thinking + 完全访问权限(Heart Orange,语义不变) |
quotaBarWarn |
#F3A115 |
#F3A115 |
账号额度条剩余不足 30%、高于 10% 的填充,其他用途不复用 |
quotaBarCrit |
#D91F37 |
#D91F37 |
账号额度条剩余不超过 10% 的填充,其他用途不复用 |
betaChannelBadgeBackground |
#DF0C27 |
#DF0C27 |
Beta 渠道开关已打开时,当前版本旁的状态徽标底色 |
betaChannelBadgeForeground |
#FFFFFF |
#FFFFFF |
Beta 渠道状态徽标文字,与底色对比度 4.98:1 |
permAutoAccent |
#417CDD |
#417CDD |
自动审批权限模式强调 |
botUnread |
#417CDD |
#417CDD |
仅限伙伴列表的未读点(桌面 --bot-unread-bg 的移动端镜像,见 DESIGN.md Bot Unread Badge) |
errorText |
#0F0F0F |
#EDEDED |
错误说明文字(跟随 textPrimary) |
errorBorder |
#858581 |
#8A8A8A |
错误边框(跟随 borderStrong) |
overlay |
rgba(38,38,38,.35) | rgba(0,0,0,.45) | modal / lightbox 背板 |
规则:
- 语义不变色(
statusReady/statusAccent/betaChannelBadgeBackground/betaChannelBadgeForeground/botUnread)跨 light / dark 一致——它们是状态语义,不随主题漂移。Beta 红色只用于设置页当前版本旁的渠道徽标,不得扩展为装饰色、错误色或 CTA。 - 浅色卡片主要靠描边分层:页面提亮到
#F9F9F6后,近白卡片相对页面只剩 1.05 的色差(桌面 1.12)。新增浮起面(卡片 / 列表行 / 浮层 / 输入容器)必须带 1pxborder,不要只靠surfaceElevated的填充色差;需要“沉下去”的块(选中底、展开块、代码卡)用比页面更暗的档。 - 文字三档由深到浅:正文 → 二级 → 三级,在所在底色上都 ≥ 4.5:1(
themeTokens.test.ts守护)。占位字单独用textPlaceholder,比三级更淡但 ≥ 3:1,只给输入框占位字用。新增文字不要拿textTertiary当“更弱的二级”以外的用途,也不要为了“更淡”自行调低透明度。 - CTA 在 dark 反相为近白:
cta近白底 +ctaText深字。注意别让近白 pill 看起来像 disabled——新增主操作 / 选中态后在 dark 下目检。 - 显示模式由用户设置:设置 → 外观 → 显示模式(跟随系统 / 浅色 / 深色,默认跟随系统)。组件只读
useTheme(),不要自己调useColorScheme()。 - Home 对话列表用 base token:列表背景 / 分隔 / 文字使用
surface/border/text*,菜单选中用surfaceChip,不另起暗色调色板;菜单 / FAB 只用 1pxborder分层、零阴影,保持桌面「单一 flat Surface + 1px Board」哲学。 - 不要在组件里硬编码 hex / rgba;找不到合适 token 时跟维护者确认是否新增,而不是写死。
3. 字体与排版
排版是过去最乱的一块(各屏自造了 ~19 个字号 + ~13 个行高)。现在收敛到一套阶梯,优先用 token 不写裸数字。
源:src/theme/tokens.ts 的 typeScale / lineHeight / fontWeight + src/theme/monoFont.ts。
文字规范速查(新增或修改任何文字前先看这张表)
2026-09-26 / 27 用户定稿。先判断这段文字的角色,再整行照抄字号、行高、字重、字色,不要按「看起来要大一点 / 淡一点」单独调某一项。
| 角色 | 字号 / 行高(token) | 字重 | 字色 | 例子 |
|---|---|---|---|---|
| 页面、弹窗、面板大标题 | 20 / 25(title) |
600 | textPrimary |
弹窗标题、首页顶栏「所有任务」 |
| 导航栏、面板顶栏标题 | 16 / 22(body) |
600 | textPrimary |
设置页顶栏「设置」 |
| 列表 / 卡片标题 | 18 / 26(subtitle) |
500 | textPrimary |
首页任务标题、队友名 |
| 行标题、选项、按钮、菜单项 | 16 / 22(body) |
500 | textPrimary(主按钮 ctaText) |
设置行标题、操作按钮 |
| 行右侧取值 | 16 / 22(body) |
400 | textSecondary |
「跟随系统」「0 个词条」 |
| 对话消息正文 | 17 / 26(bodyLarge) |
400 | textPrimary |
用户 / Agent 消息 |
| 次级正文 | 15 / 20(bodySmall) |
400(面板操作项 500) | 预览 textSecondary;操作项 textPrimary |
列表预览、面板操作项、搜索框 |
| 说明、提示、报错(成句的话) | 13 / 18(footnote) |
400 | textSecondary |
开关下的说明、表单报错 |
| 分组小标签 | 13 / 18(footnote,紧凑处可 12) |
600 | textTertiary |
设置分组标题「通知」 |
| 时间、计数、状态词(短元数据) | 12 / 18(caption) |
400 | textTertiary |
「2 小时」「3 个文件」 |
| 徽标、字母标记 | 11 / 16(micro) |
600 | 专用前景色,或 chip 底上 textSecondary |
Beta 徽标、订阅徽标 |
| 输入框占位字 | 同所在输入框 | 400 | textPlaceholder |
「今天我们做点什么呢~」 |
| 等宽代码 | 15 / 20(bodySmall)+ monoFont |
400 | textPrimary |
代码块、行内代码 |
四条硬规则(违反会被守护测试拦下,拦截点见表后):
- 字色只有五档中性色:正文
textPrimary、二级textSecondary、三级textTertiary、占位字textPlaceholder、深底上的字ctaText。不要新增一次性灰,不要拿surface当字色,不要调透明度「做淡」。 - 颜色越浅,字重不能越粗:三级色只配 400(分组小标签除外);二级色只配 400 / 500(徽标、字母标记除外)。
- 字号只用 11 档阶梯:11 / 12 / 13 / 15 / 16 / 17 / 18 / 20 / 24 / 30 / 40。成句的话至少 13。
- 每个文字样式都配行高,按上表成对;单行输入框不设行高。
登记例外(只有这些可以偏离上表,新增例外先改本节):首页列表与队友行的节奏行高(18/28、15/26、13/22);代码 / diff 的紧凑行高;对话 Markdown 标题与长文 24 行高;与相邻图标 / 按钮对齐的文字;行内强调(Markdown strong 700、搜索命中、价格折扣);登录品牌画布(见根规范 §3 豁免表)。
机器会拦什么:阶梯外字号 / 行高 / 字重与裸数字、缺行高、浅色字配粗字重(typographyTokenDiscipline.test.ts);字号阶梯本身、文字三档与占位字对比度、深浅双模式同键(themeTokens.test.ts)。拦不住、靠 review 的:角色选错(比如把说明文字放 12 号、把标题写成 500)、例外被滥用。评审时对照上表逐行看。
字号 typeScale(按角色选,2026-09-27 用户定稿收拢为 11 档)
| token | px | 角色 |
|---|---|---|
micro |
11 | 徽标、极小标签 |
caption |
12 | 短元数据:时间、计数、状态词、chip 文字。不放成句的话 |
footnote |
13 | 说明、提示、报错、备注、分组小标签。成句的话至少 13 |
bodySmall |
15 | 次级正文:列表预览、紧凑行、面板操作项、搜索框、输入框,以及等宽代码 |
body |
16 | 界面主文字:行标题、按钮、菜单项、导航栏标题 |
bodyLarge |
17 | 对话消息正文(专用) |
subtitle |
18 | 列表 / 卡片标题(首页任务、队友) |
title |
20 | 页面、弹窗、面板大标题 |
headline |
24 | 大数字、大名称 |
largeTitle |
30 | 引导页等超大标题 |
hero |
40 | 登录页品牌标题(已登记例外) |
已删除 14(listBody,并入 15)与 19(listTitle,并入 20);原 15 号 code 更名为 bodySmall。11 / 12 / 13 / 15 / 16 / 17 / 20 与 iOS 系统正文字号一致,18 / 24 / 30 / 40 为移动端自定。阶梯外字号由守护测试拦截。
行高 lineHeight(与字号配对)
每个文字样式都必须配行高(2026-09-27 用户定稿,typographyTokenDiscipline.test.ts 守护)。标准配对:
| 字号 | 11 | 12 | 13 | 15 | 16 | 17 | 18 | 20 | 24 | 30 | 40 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 行高 | 16 | 18 | 18 | 20 | 22 | 26 | 26 | 25 | 30 | 36 | 44 |
直接用 textStyles.* 预设最省事。标准之外只允许已登记的场景,不要为单个页面再造行高:
- 首页列表与队友行的节奏值(18/28 标题、15/26 预览、13/22 元数据),对话流 Markdown 标题;
- 代码、diff、媒体 hint 等「行高即盒高」的紧凑场景(
micro/bodySmall行高); - 长文阅读的
bodyRelaxed(24):登录副标题、伙伴记忆。
另有一类对齐例外:文字要与相邻图标、按钮或行内正文对齐时,行高跟随被对齐对象(如行内引用 chip、任务标签、消息操作行的时间、伙伴记忆日期)。
单行输入框(TextInput)不设行高:iOS 上会让占位字与光标偏位。多行编辑区可以配标准行高。登录品牌画布按其登记例外处理。
字重 fontWeight
regular '400' · medium '500' · semibold '600' · bold '700'(仅限已登记豁免域,见下)。UI chrome 不超过 600。
字重与字色按角色搭配(2026-09-26 用户定稿)
按元素的角色选字重,不按字号选:
| 角色 | 常用字号 | 字重 | 字色 |
|---|---|---|---|
| 页面 / 导航栏 / 弹窗 / 面板标题 | body–largeTitle |
semibold 600 |
textPrimary |
| 列表行、选项、卡片标题、按钮文字(含首页任务标题) | bodySmall–subtitle |
medium 500 |
textPrimary(主按钮用 ctaText) |
| 正文、描述、输入内容 | bodySmall–bodyLarge |
regular 400 |
textPrimary;描述性文字用 textSecondary |
| 辅助说明 | caption / footnote |
regular 400 |
textSecondary |
| 时间、元数据 | micro / caption |
regular 400 |
textTertiary |
| 输入框占位字 | 同所在输入框 | regular 400 |
textPlaceholder |
| 分组小标签(eyebrow / 区块标题)、徽标与字母标记 | micro–footnote |
semibold 600 |
分组小标签用 textTertiary;徽标 / 字母标记用专用前景色,或在 chip 底上用 textSecondary |
搭配规则:
- 颜色越浅,字重不能越粗:
textTertiary只配 400(唯一例外是分组小标签的 600);textSecondary只配 400 或 500(例外:chip 底上的徽标与字母标记可用 600,它们按图形元素处理)。 - 标题与正文靠字号 + 字重拉开;同一字号内的主次靠颜色拉开,不再用 500 / 600 细分。选中态同理(如分段选项选中只换色,字重保持 500)。
- 行内语义强调不受本表约束:Markdown strong(700,见下)、搜索命中高亮、价格折扣等局部加重保留现状。
bold '700' 只允许用在根规范 docs/design-rules/DESIGN.md §3「排版豁免登记表」登记的两处:原生 Markdown strong(src/session/MessageRenderer.tsx 的 markdownStrong)与登录品牌画布(app/(auth)/login.tsx、src/components/LoginSkinControls.tsx、src/auth/loginSkinLayout.ts)。除此之外一律不得使用 700,新增用途必须先改根规范的登记表。
等宽 monoFont
Platform.select({ ios: 'Menlo', android: 'monospace', default: 'monospace' })。禁止写死 'Courier'。
旧值 → 新 token 映射(迁移时套用)
- 字号:
10→micro·14→bodySmall(15)·19→title(20)·22/23/28→headline;成句的说明文字不要落在 12,用footnote。 - 行高:
16→caption(18)·20→body(22)或 bodySmall(20)·23→body(22)·24/25/26→subtitle(26)·28/30/31→headline(30)。 - 字重:
'700'→ 按上面的角色表选 400 / 500 / 600。已登记豁免域除外(原生 Markdown strong、登录品牌画布)——那两处保留bold '700',不要按此条降档。 - 等宽:
'Courier'与内联Platform.select→monoFont。
4. 组件约定
优先复用 primitives
新组件先去 src/components/MobilePrimitives.tsx 找,不要自造按钮 / 行 / 卡片 / 空态。已有:
- 按钮 / 行:
MainWindowActionButton·MainWindowActionGroup·MainWindowOptionButton·MainWindowRowButton·MainWindowCardButton - 头部 / 条:
ScreenHeader·SummaryStrip - 指示 / 标签:
StatusDot·ActionPill·InfoPill·MainWindowMetric - 空态:
MainWindowEmptyState - 其它共享:
CenteredScreen·ConnectionBanner·MobileVendorIcon
文本 / 卡片 / 分隔线目前仍在各屏重复定义——这是已知优化点(见执行计划),新代码尽量收敛、不要再新增一份同义样式。
设置类分组:说明文字写在卡片外(2026-10-19 用户定稿)
设置页及其二级页统一用 src/session/SettingsGroupRows.tsx 的 SettingsGroup。对齐 iOS Section footer / Android 列表辅助文字:
- 卡片里只放「名称 + 取值 / 开关 / 箭头」。成句的说明写在分组下方的
footer(13/18 400textSecondary);操作结果、权限被拒、保存失败等临时提示走messages,接在说明后面。行组件不提供hint/detail。 - 一组只配一段说明。同组几行各需说明时拆成几个分组。
- 点不了的入口不摆出来:检查更新等当前不可用的动作直接不显示,原因写进 footer,不留灰按钮加解释。
- 原地执行的动作行(检查更新、清空日志)传
chevron={false},只有进入子页 / 外链的行画箭头。 - 例外:列表条目自身的元数据(如词典别名)和录入流程里紧贴控件的步骤状态,可以留在行内。
- 「+」面板里的表单(开启协同 / 创建 Worker 等
ContextSheet*)同一规则:ContextSheetGroup的footer承载说明与校验提示(报错传footerTone="error"),ContextSheetRow用value放右侧取值、不再把说明塞进行内detail;iOS 下拉行自带行名、分段控件选项自明,分组不再加标题(Android 药丸没有行名,保留分组标题);底部主按钮撑满宽度。iOS 上「+」面板的分组标题用 13/18 600textTertiary(系统默认分组标题在新版 iOS 是大号粗体,由ComposerSectionSettingsHeader统一换掉);面板底与卡片保持系统玻璃样式,不改实色,以免丢掉原生 sheet 的玻璃过渡动画。
主题接入模式(强制)
样式随主题变化,不能再用模块级静态 StyleSheet.create。统一两种写法:
import { useTheme, useThemedStyles, type ThemeColors } from '@/theme';
import { spacing, radius, typeScale, lineHeight } from '@/theme/tokens';
// ① 样式里的颜色:模块级工厂 + hook
const makeStyles = (c: ThemeColors) =>
StyleSheet.create({
row: { borderColor: c.border, paddingHorizontal: spacing.lg },
title: { color: c.textPrimary, fontSize: typeScale.title, lineHeight: lineHeight.subtitle },
});
function Foo() {
const styles = useThemedStyles(makeStyles); // 按 scheme 缓存,热路径零分配
const { colors } = useTheme(); // ② JSX 内联色
return (
<View style={styles.row}>
<ChevronLeft color={colors.textPrimary} size={iconSize.lg} />
</View>
);
}
⚠️
makeStyles必须是模块级常量(身份稳定)。在组件体内内联定义会让useThemedStyles的 WeakMap 缓存每次 miss,退化成每帧新建 sheet,拖垮MessageRenderer这类热路径。 叶子 helper 函数若要用颜色,把colors: ThemeColors作为参数传进去,别从模块级colors取。
iOS 外壳 vs Cindy 内容
任务行滑动(2026-10-24 用户裁决,iOS / Android):右滑提供已读与置顶,全滑默认标记已读;左滑提供选项与归档,全滑归档。跨端组合沿用已有方案:已读沿用灵动岛的青绿色单勾(Lucide
Check/ SF Symbolscheckmark),归档沿用手机版的蓝色归档盒(Archive/archivebox),置顶为橙色图钉,选项为中性灰省略号。Mobile 的已读底色独立加深以保证白色图标对比度,数值由swipeActionRead管理;不把灵动岛深色背景上的高亮色直接复制到手机浅色背景。项目标题滑动(iOS / Android):仅标题整行横移,展开的子任务不随之移动。左滑露出「新建任务」,超过屏宽 55% 松手打开预填项目电脑与目录的新建页;发送后才创建任务。右滑露出「全部任务」「搜索」,必须点按,搜索限定当前项目并聚焦输入框。点标题继续展开/收起,已有滑开行时先收起操作;自定义排序仍为长按后纵向拖动。项目与任务共用滑动互斥注册表,滚动收行,左屏缘保留返回手势。动作沿用普通任务的圆形到胶囊形态,按钮直径为 56pt,间距使用 spacing.md、图标使用 iconSize.swipeAction;使用双模式 token,并通过标题的无障碍动作提供等价入口。只对有明确电脑和目录的项目启用,不把对话或 Cindy Make 聚合组视为单一目录。实现见
src/session/SwipeableProjectHeader.tsx、HomeSurface.tsx。首页导航共用组件(2026-10-13,2026-10-24 收为单一首页):iOS 首页调用 platform/chrome/HomeStackHeader,统一系统导航栏、菜单按钮与居中标题宽度;顶部模糊背景由首页路由绘制一层。页面只提供标题内容、菜单动作和右侧工具;任务标题保留长名称避让。列表、安全区、滚动指示器和下拉刷新只计算一次顶部占位。手机不再有任务/伙伴两种首页与切换转场,伙伴以任务首页的伙伴段呈现。普通页面、聊天身份栏、面板及 Android 导航暂未纳入这一批,不视为全端迁移完成。
iOS 新增与改造界面遵循 iOS 原生界面规范。该规范区分系统容器、原生控件和 Cindy 业务内容;取代原先“复杂内容面板一律使用 SheetSurface”的规定。
- 首页和简单页继续使用系统导航栏。任务页采用原生操作控件与透明标题布局,按首页实际导航中心对齐;保留返回锚点及 testID。
- iOS 弹层优先使用系统 BottomSheet,表单和操作分组优先原生 Form / Section 或分组 List。左滑任务选项已有 BottomSheet + List,可参考其关闭生命周期。任务详情与搜索的高度、材质及入口顺序见新规范。
- 消息、Markdown、代码和复杂业务内容可继续用 RN 与主题 token;业务图标保留原有 Lucide。系统导航符号由原生控件提供。不得用“原生外壳”概括成“整页已原生化”。
- 系统管理的圆角、字体、材质与反馈保留系统默认,不强制套自绘圆角档位或零阴影约束;自绘内容继续遵守本文 token 规则。
- 模型/权限、Context、账号切换等存量自绘面板列为渐进迁移项,不因本规范批量重写。Android 与必要兼容回退继续复用现有基础组件,不降低业务能力。
- 首页筛选继续使用原生 UIMenu;左侧抽屉和文件浏览顶部的存量实现不代表已经迁移,需分别审查。
- Android 首页任务行「选项」采用现有 Expo UI 的 Compose
ModalBottomSheet(SessionActionSheetFrame.android.tsx):原生容器负责拖动、遮罩、系统返回与关闭动画, 任务标题、Lucide 图标和标签操作继续复用 RN 内容及双模式 token。关闭动画完成且容器卸载后, 才通过onClosed打开重命名或删除确认;不得用固定延时推测原生动画结束。 窄屏、横屏和标签展开时内容可滚动,系统容器保留平台几何,自绘内容仍遵守本文排版规则。 账号切换、权限、标签、消息操作、分支和浏览器菜单等单层面板通过SheetModal.nativePresentation复用 Material 容器。折叠屏分区、浮动布局、二级返回与未保存表单继续保留兼容外壳, 不把不同关闭回调合并。设置、模型、权限和 Context 的普通行保留 RN 实现, 复用既有主题、排版、禁用态、独立配置按钮与业务回调,不为静态表单逐行嵌套 Compose Host。 Android 模型目录通过FlatList按可见范围分批挂载 RN 行,分组标题与模型共用列表; 使用SheetSurface.renderScrollContent替换内容滚动层,不能嵌套同向ScrollView。 搜索或来源变化须滚回首条结果,配置入口与模型选择仍是独立点击目标。 新建任务的设备、工作区和远程目录选择复用 RNNewTaskSelectionRow;设备使用原生底部弹层, 目录仍在同一兼容弹层内逐级返回,盘符通过原生菜单切换,继续调用被控端目录接口。 开关和普通文本输入原本已是原生控件;富文本编辑器不属于此次迁移。 - Android 交互跟随 iOS(2026-09-27 产品裁决):入口位置、顺序、分组、显示哪些信息与输入校验以 iOS 为准;外观保持 Android 平台实现,不照搬玻璃。贴着控件弹出的菜单统一走
NativePullDownMenu,Android 通过AnchoredPullDownMenu.android使用现有 Expo UI 的 MaterialDropdownMenu,保留分组标题、勾选、禁用、危险操作、子菜单返回行及keepPresented。弹出定位、滚动、焦点及动画交给系统;外部点击和系统返回收起原生菜单。触发器整块是一个读屏按钮,触发控件禁用时不挂菜单。例外是伙伴私聊气泡的长按菜单:气泡里有引用、链接和横向滚动,菜单不能接管整块触摸,改由调用方用同一个 RNGH 长按手势识别后,以受控方式(open/onOpenChange)打开AnchoredPullDownMenu。自绘实现保留用于兼容,不使用能力不足的基础 PopupMenu 替代。 原生菜单首次使用时创建 Compose 容器,随后随触发器复用;收起只修改expanded,保留系统关闭动画,避免每次点击重建整棵原生树。锚点的 RN 外层使用pointerEvents="none",防止关闭后的容器挡住触发器;弹出窗口独立接收菜单点击。验收必须覆盖关闭后再次打开、外部点击和菜单项选择,不能只验证首次呈现。 可勾选菜单项在原生弹出窗口中使用RNHostView承载一个 RNmenuitem,通过accessibilityState.checked表达选中、未选中和半选,禁用态与整行点击共用同一节点;勾号只是装饰,不能代替无障碍语义。现有 Compose modifier 未提供完整三态设置,不增加第二个可点击复选框。回归见androidMaterialMenu.test.tsx,模拟器须核验真实节点。
首页「所有任务」下拉只负责范围筛选:点设备名直接切换到该设备的任务,不得为补充管理动作改成设备子菜单或增加一次确认。设备详情、重命名与删除集中在左侧抽屉的「设备管理」页;列表不画进入箭头或重命名图标。所有设备无论在线、离线或未开启远程控制,都能点进资料详情,再重命名或删除;右滑显示重命名、左滑显示删除,删除需系统确认。iOS 使用系统原生列表与滑动操作。删除使用服务端接口,在线设备当前需先离线才能删除,不以本地隐藏代替删除。iOS 原生菜单与自绘回退、Android 遵守同一交互边界。
伙伴列表行与伙伴卡片(2026-09-29 定稿)
伙伴页的行与聊天里的卡片各有一个共享组件,新入口直接复用,不要另画一套:
- 列表行
CompanionListRow:私聊与群聊同一种行。行高 78,头像 44(群为双人叠放BotGroupDuoAvatar), 分隔线只画在文字列下方(从 72 到屏幕右缘)、最后一行不画;右上保留时间,第二行显示预览。 收起头像统一为 48;列表和收起态均在右下角使用 10 实心点 + 2 隔离边,与 Desktop 共用尺寸及判定。 状态优先级为待确认、异常、工作中、已完成且未读、普通未读、无状态;读到答复后清完成点,阅读不能清待确认点。 不叠工作外圈或右侧重复蓝点;有准确未读数量时保留数字。离线头像降透明度;同名伙伴加「· 电脑名」。 首次读取慢时显示同几何的骨架行。 - 聊天顶栏
ChatIdentityHeader:私聊与群聊共用。返回 + 32 标记 + 标题 16/22 600 + 副标题 12/18 三级色 + 设置;点身份区与设置打开同一份资料 / 设置。私聊副标题保留设备名,离线时前面加「离线 ·」。 伙伴 Todo 使用顶栏中的独立待办入口,只在宿主返回该能力链接时显示;复用44px玻璃按钮与原身份布局, 不替代设置,不影响群聊,不新增手机例行任务管理。 - 卡片外壳:
surfaceElevated底 + 1pxborder+radius.container+ 内边距 16。眉题 13/18 medium 二级色, 标题 16/22 medium,状态行 13/18 二级色;只有运行中(statusAccent呼吸)与失败(statusError)带颜色。 - 卡片按钮
CompanionCardButton:高 38(hitSlop 补到 44)、pill、15/20 medium,文字始终居中;一行里等宽 平分,次要在左、主操作在右;次要按钮用surfaceChip填充不加描边。不要在卡片里写textAlign: 'left'的按钮。 - 动效:新消息与卡片用
CompanionEntering/CompanionFadeIn(RNAnimated,原生驱动,只动 opacity / transform,系统减弱动效时静止);工作中用CompanionPresenceRing+ThinkingDots,不另写循环动画。
待发送气泡(2026-10-21 定稿,任务与伙伴私聊共用)
PendingSendBubble 是自己刚发出、还没被确认的消息。稿件:Designs/cindy/send-bubble(选定 B 方案)。
- 一直是实色:点发送当帧上屏,与正式气泡同款;网络往返、排队、等电脑都不变灰。只有「正在下方输入框编辑」时淡化。
- 状态只放两处:气泡左侧图标(转圈 = 发送中 / 上传中,队列图标 = 排队中,时钟 = 等电脑或网络,红色感叹号
statusError= 失败),以及气泡下方那一行。送达后正式消息的「复制 / …」占的就是这一行,所以前后行高不变、列表不跳。 - 本机刚发出的消息:0.6 秒内不出任何状态,慢了才淡入转圈;入场上浮一次,确认时不重播。
- 下方那一行:排队中「排队中 | 插话 编辑 取消」;失败「未发送 | 重试 删除」,有具体原因时原因写在下面;等待「等电脑连上后发送 | 取消」。文字 13/18,按钮命中区补到 44。报错文字保持黑白(
errorText),只有左侧图标是红色。 - 带图:每张图自己转圈;只有那张没传上去的图上显示重传按钮。
5. 间距 / 圆角 / 触控 / 安全区
- 间距
spacing:xs 4 · sm 8 · md 12 · lg 16 · xl 24 · xxl 32(基数 4)。避免2 / 6 / 13 / 17这类裸数字;1-2pt 的微调若实在需要,集中、少量、写注释。 - 圆角
radius:四档阶梯——micro 4/control 8/container 12/pill 9999(定义与各档用途见src/theme/tokens.ts,守护测试designTokenDiscipline.test.ts拦截字面量与 token 算术)。禁止阶梯外值。 - 触控目标:主操作命中区 ≥ 44×44(iOS HIG)。可见图标可小(14–18),用
hitSlop或不可见外层把热区补到 44。 - 安全区:屏幕根用
SafeAreaView(react-native-safe-area-context);需要精确 inset 用useSafeAreaInsets()。键盘遮挡用KeyboardAvoidingView+ inset,务必开软键盘实测。
6. 图标
- 库:lucide-react-native(统一,不混用其它图标库)。
- 图标选择必须与桌面版保持一致:同一动作 / 语义,手机和桌面用同一个 lucide 图标。新增图标前先去桌面对应组件确认它用的是哪个(如权限模式用
Hand/CodeXml/ClipboardList/Sparkles/TriangleAlert,见桌面new-chat/PermissionSelector.tsx),不要另选近似图标(如别用Shield系列代替)。这样跨端心智模型一致。- 已沉淀的对齐映射:权限模式的图标 + 语义色见
src/session/permissionPresentation.ts(严格对照桌面 PermissionSelector:auto→permAutoAccent、bypassPermissions→statusAccent,其余中性)。 - 伙伴私聊回复:消息下方的回复按钮使用
ChatReplyIcon,与 Desktop 共用同一款扁圆、下尾的纯气泡路径。复用原「添加到对话」操作,并从伙伴更多菜单移除重复入口;普通任务的「添加到对话」仍用MessageSquarePlus。手机尚未提供的群聊/话题引用回复入口不因此新增。实现见src/session/CompanionMessageActions.tsx。 - 模型下拉对齐桌面 provider-aware 结构:同一 model 可挂多家「供应商(来源)」,选行 = 选「来源 + 模型」,选择经 device-link 把
model + providerId路由到被控端。复用@cindy/model-providers的buildProviderSections作分段唯一真相(src/session/providerModelSections.ts),被控端供应商目录经隧道maker:provider:list取(src/device-link/useDeviceProviders.ts);0 供应商 / 旧被控端回退 capabilities 扁平列表。来源 mark 与桌面同源:三个内置供应商(Claude / Codex / XD)用官方单色 SVG mark(path 常量在src/components/vendorIconPaths.ts,与桌面 ClaudeMark / CodexMark / XDIncMark 逐字同源),自定义供应商回退首字母 monogram(MobileProviderMark)。早期「手机故意不搬品牌 SVG、全用 monogram」的决策已在「模型选择列表与桌面完全对齐」改造(2026-07)中推翻:react-native-svg 本就在依赖里,复制 path 常量零成本,而跨端一眼可辨的来源图标价值更高。唯一保留差异:monogram 容器用 pill 圆角(桌面 4px 方盒)——圆角遵守手机二元规则,不引入中间值。 - Agent 身份与厂牌分槽:
MobileAgentMark/MobileVendorIcon只表示运行时 Agent,使用 Claude Code 像素脸或 Codex CLI>_多瓣花;Anthropic / OpenAI 来源与模型品牌继续由MobileProviderMark/MobileModelIconMark表示。两类 mark 即使名称相近也不得互换。
- 已沉淀的对齐映射:权限模式的图标 + 语义色见
- 设备「已撤销访问权限」状态:控制端(手机)被某台被控电脑撤销访问时,设备 chip 用
Lock图标(colors.textSecondary)替代状态圆点 —— 与「离线 / 未开启远控」的灰圆点明确区分,读作「被锁在外」,且不引入非调色板色(遵守 §1 灰度 + teal/orange 约束)。无桌面对端:桌面是被控方(管理「允许哪些控制器」),没有「控制器被撤销」这一侧视图,故此处不套用「与桌面同图标」规则。点按该 chip 弹RevokedAccessTip(说明 + 「重试访问」),重试复用 device-link 探测路径(成功经withAccessRevokedHandling清除本地撤销标记);重连 / 回前台也会静默重试自愈。 - 移动端可以比桌面更省:紧凑工具栏里的触发器只放图标、不带文字标签(桌面 PermissionSelector 是图标+文字,手机为省空间只留图标);但展开后的下拉面板仍按桌面给出图标 + 文字 + 选中态的完整选项。
- 尺寸走
iconSize:xs 12 · sm 14 · md 16 · lg 18 · xl 22 · xxl 26(md/lg最常用)。避免 17 个散乱尺寸。 strokeWidth统一约 2。- 颜色走 token(
colors.textPrimary/textSecondary/statusAccent/permAutoAccent等),不写死。 - 会话 Agent 身份图标走
MobileVendorIcon;provider / model 厂牌图标分别走MobileProviderMark/MobileModelIconMark。 - 底部浮窗按平台承载:iOS 新增与迁移优先系统 sheet,详情默认中等高度、短工具按内容高度,具体见 iOS 规范。Android 和尚未迁移的兼容实现继续复用
SheetModal/SheetSurface,不另造自绘外壳;其二级内容保留单 Modal 内导航。不同面板之间等待关闭回调后再呈现,避免叠加遮罩。 - 创建群表单(2026-10-28 用户修正):iOS 使用展开的系统 page sheet 与 UIKit 导航栏,正文采用不透底的主题 surface。左侧为系统关闭图标按钮,右侧为文字创建按钮,均保留中性玻璃底;创建不用蓝色或 prominent 填充。标题、按钮几何与交互由导航栏负责,不在内容里用自定义标题行模拟 toolbar。表单可滚动并避让键盘,呈现完成后聚焦群名;有草稿或提交中禁止滑动关闭,显式关闭沿用丢弃确认。
7. Do / Don't
Do
- 页面背景用
surface,抬层用surfaceElevated,chip/选中用surfaceChip。 - 交互元素 pill(9999),容器 12,二选一。
- 颜色 / 字号 / 行高 / 圆角 / 图标尺寸全部走 token。
- 主题色走
useThemedStyles/useTheme,跟随系统 light/dark。 - 复用
MobilePrimitives,优先减法。
Don't
- ❌ 写死 hex / rgba /
'Courier'(dark 下不变色 / 字体不统一)。 - ❌ 未登记的阴影(首页主菜单抽屉例外见 §1)。
- ❌ 中间圆角(0 / 3 / 4 / 8 / 28)。
- ❌ UI chrome 字重 > 600(已登记豁免域除外:原生 Markdown strong、登录品牌画布)。
- ❌ 在组件体内内联定义
makeStyles(破坏缓存)。 - ❌ 渐变、装饰性插画、品牌色泛滥。
8. Token 速查 + 选择规则
背景层选择:页面=surface;浮起的卡片/输入框/弹窗=surfaceElevated;chip/pill/选中行=surfaceChip;hover/pressed 用透明度(pressed: { opacity: .72 })而非新色。
文字层级:主=textPrimary;次=textSecondary;三级=textTertiary;占位字=textPlaceholder;深底上的字=ctaText(不要用 surface 当字色)。主界面中性字色只有这五档,不要新增一次性灰。字重按 §3「字重与字色按角色搭配」选,浅色字不配粗字重。
CTA:主操作填充 cta + 文字 ctaText(dark 自动反相);次要操作用边框 + textPrimary。
字号角色:见 §3 字号表——短元数据 caption、成句说明 footnote、次级正文与代码 bodySmall(代码配 monoFont)、主文字 body、对话 bodyLarge、列表标题 subtitle、页面标题 title。
迁移 / 新建 checklist
- 每段文字都能在 §3「文字规范速查」里找到角色,字号 / 行高 / 字重 / 字色整行一致(例外已登记)。
- 颜色全走
useThemedStyles(makeStyles)+useTheme().colors,无裸 hex/rgba。 -
makeStyles在模块级定义。 - 字号 / 行高 / 字重 / 圆角 / 图标尺寸全走 token,无裸数字(必要微调写注释)。
- 等宽用
monoFont。 - 无未登记的阴影(首页主菜单抽屉例外见 §1)、无中间圆角、UI chrome 字重 ≤ 600(已登记豁免域除外:原生 Markdown strong
src/session/MessageRenderer.tsx、登录品牌画布app/(auth)/login.tsx/src/components/LoginSkinControls.tsx/src/auth/loginSkinLayout.ts—— 这两处保留bold '700',验收时不要按 ≤ 600 降档)。 - 复用了
MobilePrimitives,没有重复造按钮/卡片/空态。 - 在模拟器 light + dark(Cmd+Shift+A)都目检过。
交叉引用:桌面 docs/design-rules/cindy-design-system.md §2(颜色)/ §3(排版)/ §10(token 架构)。本文是其轻量移动版;色值由移动端独立决定,规则见 DESIGN.md §15.13。