@tfdesign/b-end 1.0.4

package/skills/tfds/DESIGN_PRINCIPLES.md

@@ -0,0 +1,477 @@
+# TFDS B 端设计原则（设计品味与体验判断）
+
+> **作用域**：生成任何 TFDS B 端页面前，先用本文件判断页面气质、信息优先级和 UX 取舍。
+>
+> 本文件回答“为什么这样设计、如何取舍”；具体组件、props、token 和布局骨架仍以 `components.index.json`、`LAYOUT_RULES.md`、`GLOBAL_DESIGN_RULES.md` 为准。
+
+---
+
+## 目录
+
+- §0 一句话定位
+- §1 设计哲学
+- §2 视觉调性
+- §3 平台视觉 DNA（标杆页面沉淀）
+- §4 页面层级判断
+- §5 页面类型设计判断
+- §6 组件设计角色
+- §7 生成前决策流程
+- §8 生成后设计自检
+- §9 与其他规范的关系
+
+---
+
+## 0. 一句话定位
+
+TFDS 是面向企业级 B 端平台的高密度浅色系统，适用于管理后台、运营平台、数据平台、客服工作台、配置中心、审核系统、流程工具和 AI 辅助工作台等场景。页面应当专业、克制、清晰，把任务、数据、输入、流程和协作放在视觉中心。品牌青绿用于交互与状态信号；AI 渐变只在明确智能能力场景中作为语义信号，不作为装饰背景。
+
+---
+
+## 1. 设计哲学
+
+### 1.1 任务先于装饰
+
+用户打开 B 端页面是为了完成任务，不是欣赏视觉包装。页面第一屏必须让用户立刻知道：
+
+- 当前在处理什么业务对象
+- 当前最重要的状态或风险是什么
+- 下一步最合理的操作在哪里
+- 需要输入、筛选、对比、确认或查看的内容在哪个区域
+
+如果某个视觉元素不能帮助完成以上任一目标，就不要加。
+
+### 1.2 内容先于容器
+
+TFDS 的容器负责承载工作流，不负责抢视觉权重。大白卡、面板、分区只提供稳定边界；真正的层级来自标题、状态、控件和数据本身。
+
+- 最外层工作白卡：纯白底 + 12px 圆角 + 无 border + 无 shadow
+- 白卡之间：靠灰底与 8px 间距分层
+- 白卡内部：由 FormTitle、Tabs、Table、Form、TextArea、ChatInput 等组件建立功能区
+- 内部控件描边保留，白卡外边界不加描边
+
+### 1.3 层级靠结构，不靠大字号
+
+TFDS 不用“大标题 + 大留白 + 重阴影”制造气势。企业工作台更需要稳定扫描。
+
+- 标题默认用 `FormTitle`，字重 600
+- 常规 UI 字号以 14px 为主体，标题通过 600 字重和组件结构区分
+- 页面只允许少量 18px / 20px 标题，避免整页所有模块都在喊话
+- 强调信息优先用位置、分组、Tag 和操作优先级表达，不靠 `font-bold` 或任意字号
+
+### 1.4 高密度但可扫描
+
+TFDS 的密度应当像成熟企业软件：信息多，但不乱。
+
+- 同组元素用 8px 或 12px，表单字段用 16px，白卡内 padding 用 24px
+- 表格、列表、会话、编辑器应撑满可用空间，而不是堆成窄窄一列
+- 重要说明完整展示；列表预览、文件名、模型 ID 可省略，但必须配 Tooltip 或详情入口
+- 不为了“留白好看”牺牲数据对比效率
+
+### 1.5 智能能力是局部身份信号，不是全局装饰主题
+
+TFDS 不只服务 AI 工作台。AI 渐变只在页面存在明确智能能力时出现，并只服务于 AI 相关对象，例如 AI 输入框、AI 消息、AI 推荐、AI 执行流、AI 标识。不要把 AI 渐变铺到普通卡片、页面背景、按钮、统计模块上，也不要让非 AI 平台页面带上“为了显得智能”的装饰感。
+
+---
+
+## 2. 视觉调性
+
+### 2.1 基础气质
+
+- **专业**：对齐、清晰、稳定，避免花哨装饰
+- **克制**：品牌色少量出现，阴影和渐变不泛用
+- **轻盈**：浅灰底 + 白色工作区，靠明度差和圆角分层
+- **可信**：状态语义明确，危险、警告、成功、信息不能混用
+- **企业平台感**：结构稳定、信息密度适中，既能承载通用管理后台，也能承载 AI 辅助工作流
+
+### 2.2 色彩使用
+
+- 页面底色：浅灰 `var(--color-blueGrey-200)`，用于承载整页工作区
+- 白卡底色：`var(--color-surface)`，用于承载真实工作内容
+- 主文字：`var(--color-foreground)`，次级说明：`var(--color-foreground-secondary)` / `muted`
+- 品牌青绿：只用于焦点、激活、链接、品牌状态、标题竖条
+- 语义色：只用于状态反馈，不用于装饰
+- AI 渐变：只用于 AI 语义面，不用于普通业务面
+
+### 2.3 禁止的视觉倾向
+
+- 禁止营销页式 hero、彩色光斑、大面积渐变背景，除非当前页面就是明确的 AI 入口页模板
+- 禁止普通白卡加重阴影、灰色描边、黑色边框来“显得有层次”
+- 禁止整页多个黑色主按钮并列，主操作必须收敛
+- 禁止把 Tag、Button、Tabs、Card、FormTitle 用 `div/span` 手搓相似样式
+- 禁止用随机 `text-[15px]`、`p-[18px]`、`#333`、`bg-gray-*` 填补审美空白
+
+---
+
+## 3. 平台视觉 DNA（标杆页面沉淀）
+
+### 3.1 灰色应用壳 + 白色工作区
+
+TFDS 平台不是白底网页，也不是传统后台的强边框面板。标准气质是浅灰应用壳承载多个白色工作区。
+
+- 最外层是浅灰画布，导航、页头、分区间距都坐在灰底上
+- 真正工作内容进入白色大圆角区域，白卡之间用 8px 灰底缝隙分层
+- 白卡不靠边框和阴影强调，靠明度差、圆角、内容标题和控件边界建立层级
+- 页面贴近浏览器边缘，不做居中 `max-width` 后台页面
+
+### 3.2 平台导航是“窄侧栏 + 顶部语境切换”
+
+标杆页面普遍使用两层导航：左侧窄导航负责产品/业务域，顶部胶囊负责当前模块或工作模式。
+
+- 左侧导航窄、轻、稳定，图标为主，当前业务项用浅底或品牌色信号提示
+- 顶部模块切换优先用胶囊 Tabs / segment，选中态可以是黑色实心胶囊，未选中态保持灰色轻量
+- 页面右上角放全局操作，主操作用黑色 primary，次要操作用白底描边或 icon button
+- 不要把顶部导航、页面标题和操作按钮塞进白卡内；它们属于应用壳
+
+### 3.3 选择态是细信号，不是大面积染色
+
+TFDS 的选中、激活、当前态都很克制。
+
+- 表格或列表选中：使用品牌描边、左侧细竖条、浅品牌底或小图标，不整块强色填充
+- 顶部模块选中：可以使用黑色胶囊，形成明确当前模式
+- 状态徽标：使用低饱和浅底 Tag，避免大面积红/绿/橙背景
+- hover 只做轻微底色、描边或阴影变化，不做浮夸动效
+
+### 3.4 信息密度高，但阅读路径清楚
+
+标杆页面的密度来自稳定排布，不是把控件挤小。
+
+- 表格行高、列表项高度保持充足，文字 14px 为主，元信息 12px
+- 核心对象名用 600 字重，描述和时间戳用 muted 色
+- 筛选区靠近内容标题，筛选控件横向排布且固定宽
+- 分页、总数、每页数量固定在列表底部，不漂浮在内容中间
+
+### 3.5 工作台优先分屏，不堆叠
+
+复杂任务页不是 Dashboard 堆卡片，而是把“上下文、工作内容、配置/详情/产物”分成稳定面板。
+
+- 常见骨架：左侧列表/会话/进程，中间主工作区，右侧详情/配置/预览
+- 每个面板只承担一个职责，面板头固定，正文内部滚动
+- 左侧用于定位和上下文，中间用于编辑/对话/主内容，右侧用于参数、详情、产物或结果
+- 不要把三类内容纵向堆成一个长页面；那会破坏工作流对照
+
+### 3.6 内容产物要像“可交付物”，不是普通卡片
+
+报告、文档、HTML 预览、策略说明、运行产物需要被当作主内容画布处理。
+
+- 产物区通常占据最大面积，使用大白内容画布
+- 顶部只保留必要标题、状态和工具图标，减少容器噪音
+- 正文排版以可读性为优先，段落、标题、图表、指标卡要形成文档式阅读节奏
+- 产物预览不要压缩成多个小卡片，也不要被 AI 进程面板抢占视觉中心
+
+### 3.7 AI 辅助是伴随式，不默认主宰页面
+
+标杆页面中的 AI 能力通常以“进程、建议、输入、产物生成”方式嵌入工作流，而不是把所有页面都变成聊天页。
+
+- 用户未进入具体上下文时，可以使用居中的 AI 输入入口
+- 用户已经在处理对象时，AI 应在侧栏、底部输入框、进程卡或建议区中辅助
+- AI 进程卡使用轻灰容器、步骤状态和简短总结，避免大段营销式解释
+- 只有明确的 AI 入口页，ChatInput 才成为页面中心；管理页和配置页仍以对象和任务为中心
+
+---
+
+## 4. 页面层级判断
+
+### 4.1 页面元信息直接坐灰底
+
+页面级标题、返回、面包屑、页面级 Tabs、页面主次操作属于页面元信息，应直接放在灰底上。不要为了“规整”把页面 header 再包一张白卡。
+
+适用对象：
+
+- 页面标题和描述
+- 页面级主按钮、导出、创建、同步等操作
+- 页面级筛选入口或全局切换
+- 返回、面包屑、产品级上下文
+
+### 4.2 白卡只承载工作内容
+
+白卡应当承载用户真正要处理的内容：
+
+- 表格、列表、筛选结果
+- 表单配置、字段编辑
+- Prompt / JSON / 代码 / 参数编辑区
+- 对话流、消息列表、客服会话
+- 运行结果、审核结果、风险明细
+
+不要把“页面标题 + 描述 + 操作按钮”单独包成一张白卡。那会让页面失去主从关系。
+
+### 4.3 区分工作白卡和 Card 组件
+
+TFDS 中有两类“卡片”，不能混用：
+
+- **工作白卡**：页面布局容器，纯白底、12px 圆角、无 border、无 shadow，通常由页面骨架创建。
+- **Card 组件**：业务摘要、入口卡、信息卡，使用组件自身样式和 props。它不是所有白色容器的替代品。
+
+不要把 Card 的玻璃感、hover 阴影、20px 圆角套到所有工作白卡上。工作白卡遵守 `GLOBAL_DESIGN_RULES.md` 的白卡铁律。
+
+---
+
+## 5. 页面类型设计判断
+
+### 5.1 平台壳 / 模块工作区
+
+目标是让用户明确当前产品域、当前模块和页面主操作。
+
+- 左侧 NavBar 保持稳定，不随内容滚动
+- 顶部模块切换、版本切换、发布/保存/创建等动作直接坐灰底
+- 当前模块用黑色胶囊或轻量激活态表达，不用大面积品牌色
+- 右上角主操作保持固定位置，不能藏在白卡内部
+
+### 5.2 列表 / 管理页
+
+目标是快速筛选、对比、批量处理。第一优先级是表格或列表的可扫描性。
+
+- 先选列表/管理类 page-template
+- 页面级主操作只保留一个，例如“新建”
+- 筛选栏控件固定宽，不要全部满宽
+- 标题、业务范围 Tag、筛选区、表格之间要形成一条自然的纵向扫描线
+- 表格容器撑满剩余高度，避免页面滚动和表格内部滚动同时混乱
+- 表格行分隔线轻，行内容靠列对齐和弱文字建立密度
+- 状态、风险、类型必须用 Tag，不手写彩色徽标
+
+### 5.3 分类 + 列表页 / 知识库页
+
+目标是让用户先定位分类，再处理右侧对象。
+
+- 左侧用 TagBar / 分类列表表达结构
+- 右侧用 Table / 列表表达工作对象
+- 需要查看全文、说明、案例详情时，右侧增加详情面板，而不是弹窗打断
+- 左侧宽度固定，右侧 `flex-1 min-w-0`
+- 分类数量不要做成一排 Button
+- 当前分类、数量、筛选条件要贴近列表标题
+- 列表项选中态优先用品牌描边或轻底色，详情面板用白色内容容器承载富文本
+
+### 5.4 Tab 顶栏 / 策略详情 / 编辑详情页
+
+目标是让用户在同一对象下切换视图。
+
+- 同一容器内的互斥视图必须用 Tabs
+- 内容区 Tabs 默认 sm
+- 顶部上下文信息应轻量，不喧宾夺主
+- 详情区和列表区要有明确主从，不要双区域都做成强标题
+- 编辑详情页常见三分区：左侧上下文/进程，中间编辑器或画布，右侧配置/说明/单测
+- 中间编辑器应占最大视觉面积，右侧配置区窄而稳定
+
+### 5.5 托管 / 客服 / 会话工作台
+
+目标是高效处理队列、会话上下文和下一步动作。
+
+- 左侧队列按状态分组，当前项用品牌左边条或轻底色突出
+- 中间会话/处理流保持纵向时间线，重要任务卡使用轻灰容器承载
+- 待确认、托管中、已挂起、异常等状态必须用 Tag 或固定状态区表达
+- 底部输入或确认动作固定，不随会话流滚走
+- 右侧详情、用户画像或工单信息只作为辅助，不抢会话主线
+
+### 5.6 Playground / 调试台 / Prompt Editor
+
+目标是输入、参数、运行、结果在同一屏完成对照。
+
+- 整页不滚，面板内部滚
+- 多面板同高，标题固定，正文滚动
+- Prompt、JSON、代码、日志优先用 TextArea `variant="code"` 或规范代码容器
+- 运行按钮、模型参数、结果状态要靠近工作流，不要散在页面角落
+- 输入区和输出区不要被大留白隔开
+
+### 5.7 入口页 / 首页 / AI 入口页
+
+目标是降低开始成本，不是做营销落地页。普通企业平台首页应突出业务入口、待办、数据概览和最近访问；AI 入口页才突出 ChatInput 和智能推荐。
+
+- 普通首页的核心入口、待办和关键数据必须是视觉中心
+- AI 入口页的 ChatInput、推荐问题、快捷动作、历史入口要围绕输入组织
+- AI 渐变只在 AI 入口或智能模块中出现，用于身份信号
+- 模板/案例卡片放在入口下方，作为“下一步可选路径”，不要抢输入主行动
+- 不要做大面积品牌背景、漂浮装饰、无功能的 slogan 区
+
+### 5.8 Copilot / 产物预览页
+
+目标是主工作区和 AI 辅助区并行，最终产物清晰可读。
+
+- 主内容占主导，AI 侧栏辅助决策
+- AI 建议必须可执行、可采纳、可忽略
+- 侧栏宽度固定或有合理上下限，主区 `min-w-0`
+- 不能让 AI 面板挤压表单标题或正文导致一字一行
+- 产物预览区占最大面积，工具栏轻量贴顶，文档正文不被过度卡片化
+
+### 5.9 三步配置 / 批测 / 评估流
+
+目标是让用户按步骤完成配置，同时保留跨步骤对照。
+
+- 多步骤配置优先横向三栏或分区并列，而不是纵向长表单
+- 步骤编号用小黑底数字或明确序号，标题简短
+- 每栏白卡内部再使用轻描边子区块承载选项、预览和参数
+- 中间预览/评估对象要保持可见，右侧配置不要挤压它
+- 发起评估、发布、保存等主操作固定在顶部右侧
+
+### 5.10 会话 / 客服 / IM 页
+
+目标是清楚处理“谁在说、说了什么、当前状态、下一步动作”。
+
+- 消息必须使用 ChatMessage / ChatBubble / IMConversationPattern
+- 输入区固定底部，消息流内部滚动
+- 人工、AI、用户、系统状态必须视觉区分
+- 工单、订单、用户画像等辅助信息放侧栏，不要挤进聊天流
+- 高风险、待跟进、已解决等状态用 Tag 和固定位置表达
+
+### 5.11 空状态 / 无权限 / 建设中
+
+目标是解释原因并给出下一步。
+
+- 优先使用 Empty 或对应 page-template
+- 文案短，说明原因 + 一个主行动
+- 不要堆多个按钮
+- 不要用大面积插画替代明确操作
+
+---
+
+## 6. 组件设计角色
+
+### 6.1 NavBar / Top Tabs / TagBar
+
+导航组件表达“我在哪里”和“我正在处理哪一类对象”。
+
+- NavBar 负责产品域和一级业务，不承载页面筛选条件
+- 顶部 Tabs / segment 负责当前模块、模式、版本或工作台切换
+- TagBar / 分类树负责对象过滤和知识分类，不要用按钮组冒充
+- 当前态必须稳定可见；未选中态保持轻，不要每个项都加高饱和颜色
+
+### 6.2 FormTitle
+
+FormTitle 是页面语义锚点，不是装饰竖条。
+
+- 页面总标题、白卡标题、面板标题、section 标题都先用 FormTitle
+- 标题字重必须由组件内部保持 600，不外部覆写
+- 状态和数量贴主标题右侧，用 `titleSuffix`
+- 普通标题默认不展示 description
+- 只有确实需要解释业务规则、风险、空状态原因时才开启 description
+
+### 6.3 Button
+
+Button 表达操作优先级。
+
+- 每个区域最多一个 primary
+- 普通操作用 outline / ghost / text，而不是继续增加 primary
+- 危险操作必须有语义区分，不能伪装成普通按钮
+- 低频操作收进更多菜单或 icon button，避免工具栏变成按钮墙
+
+### 6.4 Tabs
+
+Tabs 表达同一区域内的视图切换，不表达状态标签。
+
+- 分段切换用 `variant="segment"`
+- 内容区默认 sm
+- 页面级或产品级导航才考虑 md / lg
+- 不要用一排 Button 或 Tag 冒充 Tabs
+
+### 6.5 Form 控件
+
+表单控件承载输入任务，默认应稳定、清晰、可预测。
+
+- 主区、筛选栏、弹窗、抽屉中的 Input / Select / Button 默认 md
+- 表格行内或极窄工具条才用 sm
+- 筛选栏：多个字段并排，固定宽
+- 白卡正文单列字段：默认满宽
+- 必填、错误、禁用、帮助说明使用组件内能力，不手写状态样式
+
+### 6.6 TextArea / 代码输入
+
+TextArea 是长内容编辑器，不是普通多行 div。
+
+- 普通描述、备注、工单详情用默认 TextArea
+- Prompt、JSON、SQL、日志、代码参数用 `variant="code"`
+- 代码类文字必须保持 14px / 20px 节奏
+- 主编辑区使用 `fillHeight`，让控件内部滚动
+- 不手写原生 textarea + 行号列
+
+### 6.7 Table / 列表
+
+Table 承担 B 端最重要的数据对比。
+
+- 表格优先保持稳定行高和列对齐
+- 状态列用 Tag
+- 操作列收敛，低频操作用更多菜单
+- 长文本可省略，但必须有 Tooltip 或详情入口
+- 表格不要被包进多层窄容器导致横向拥挤
+
+### 6.8 Card
+
+Card 用于业务摘要、入口、对象概览，不是通用白卡容器。
+
+- 父级灰底时可用 `color="white"`
+- 父级白底时用 `color="grey"` 做次级容器
+- 摘要卡内部要有明确标题、状态、主指标或下一步入口
+- 不要用 Card 承载大篇幅表单、表格、对话流
+
+### 6.9 Chat 组件
+
+Chat 组件表达消息和 AI 工作流。
+
+- 所有消息用 ChatMessage / ChatBubble
+- 用户、AI、系统、客服角色必须清楚
+- 先判断会话背景，再选气泡色：AI 问答、任务执行、Copilot、流程跟进等执行类对话优先浅灰背景 `var(--color-blueGrey-200)`；常规 IM、客服进线、人工接待、站内信回复优先白色背景 `var(--color-surface)`
+- 浅灰背景：左侧用户气泡用 `incomingTone="grey"`，右侧普通回复用 `outgoingTone="white"`；只有明确 AI / 机器人执行回复时才用 `outgoingTone="ai"`
+- 白色背景：左侧用户气泡用 `incomingTone="grey"`，右侧人工/客服回复用 `outgoingTone="default"`，右侧 AI/机器人回复用 `outgoingTone="ai"`；禁止白底上再叠无描边白气泡
+- ChatMessage 的 `role="user"` 用户气泡默认使用 `userBubbleTone="auto"` 自动适配：白色大背景 / 白色工作卡内自动变为 `fill-default` 灰气泡；浅灰、蓝灰、AI 会话灰底等非白背景自动保持 `surface` 白气泡。生成页面默认不要手动传 `userBubbleTone`；只有复杂背景无法识别时才显式传 `surface` / `fill`
+- AI 建议、执行过程、追问按钮使用组件能力
+- 输入区用 ChatInput，不手写渐变输入框
+
+### 6.10 Modal / Sheet / FullScreenPage
+
+浮层表达打断强度。
+
+- 轻量确认用 Modal
+- 侧向配置或详情查看用 Sheet
+- 复杂编辑、长流程、沉浸任务用 FullScreenPage
+- 浮层里同样遵守一主操作原则
+
+---
+
+## 7. 生成前决策流程
+
+每次生成页面前，按顺序回答：
+
+1. 这是哪类页面：平台壳、列表管理、分类列表、知识库详情、策略编辑、托管会话、首页、配置中心、数据看板、Playground、AI 入口、Copilot、产物预览、批测评估、表单、空状态？
+2. 用户第一眼必须看到什么：状态、数据、输入框、对话、风险还是主操作？
+3. 是否已有 page-template / page-pattern 命中？
+4. 每个 UI 元素是否已有组件命中？
+5. 如果组件未覆盖，自定义区块是否完全使用 `GLOBAL_DESIGN_RULES.md` token？
+6. 页面滚动模型是什么：整页滚、面板内滚、表格内滚还是消息流滚？
+7. 页面是否需要分屏对照：左上下文 / 中主工作区 / 右配置详情？
+8. 是否有一个明确主操作，其他操作是否降级？
+
+答不出来时，先回到 `components.index.json` 和 `LAYOUT_RULES.md`，不要开始写代码。
+
+---
+
+## 8. 生成后设计自检
+
+交付前必须检查：
+
+- 页面是否像“企业级 B 端平台”，而不是营销页、普通 admin 模板或随机 shadcn 页面
+- 是否符合“灰色应用壳 + 白色工作区 + 轻导航 + 黑色主操作”的平台气质
+- 页面 header 是否直接坐灰底，白卡是否只承载工作内容
+- 最外层白卡是否无 border、无 shadow、12px 圆角
+- 复杂任务是否采用稳定分屏，而不是纵向堆叠成长页面
+- 列表/表格是否撑满工作区，筛选、分页和详情是否位置稳定
+- 入口页是否把主行动放在视觉中心，模板/案例卡片是否作为辅助路径
+- 产物预览是否像可交付文档，而不是被压缩成普通信息卡
+- 所有标题是否使用 FormTitle，且字重没有被外部覆写
+- 所有已有组件是否整体 import 使用，没有手搓相似样式
+- 品牌青绿是否只用于焦点、激活、链接、品牌状态和标题竖条
+- AI 渐变是否只出现在 AI 语义面
+- 字号、间距、圆角、阴影是否全部来自 token 或组件默认值
+- 主操作是否收敛，每个区域是否最多一个 primary
+- 长文本是否不会静默裁切，省略是否有 Tooltip 或详情入口
+- Playground / 会话 / 多面板页面是否没有错误地整页滚动
+
+---
+
+## 9. 与其他规范的关系
+
+当本文件与具体实现规则发生冲突时，按以下优先级执行：
+
+1. `components.index.json` 的组件 rules / examples
+2. `SKILL.md` 的硬规则和 Checklist
+3. `LAYOUT_RULES.md` 的页面骨架、宽高、自适应、滚动规则
+4. `GLOBAL_DESIGN_RULES.md` 的 token、白卡、字体、间距、文本规则
+5. 本文件的设计原则和 UX 取舍
+
+本文件不能用来绕开组件调用、token 约束或布局铁律。它只负责让 AI 在正确规则内做更专业的页面判断。