样例:产品设计规范
公开教程 · 无需登录

样例:产品设计规范

下面是 CampusClaw 项目《产品设计规范 · CampusClaw》的原文,逐条列出,可直接照抄。

适用:frontend/src 下的页面、组件与文案
被谁读到:规则文件 .cursor/rules/product.mdc,globs frontend/src/**/*.{ts,tsx}

1. 用户与场景写死在 README 里

两类角色,三个场景:

角色场景落到的页面
教师上传本班资料、查看本班提问记录/console(上传与技能管理)、/console/ask-logs
学生检索本班资料、提问、追看出处/materials、/materials/{id}、/ask
学生回看自己的历史会话/sessions、/sessions/{id}

每条能力的场景都要落得到某个页面;落不到的,先回去改规约。

2. 术语表:一个概念只有一个词

面向用户面向接口禁止出现
资料material_id文档、文件(文件专指上传的附件)
切片chunk_index分片、段落(语义不同)
出处citation引用来源、参考链接混用
班级class_id租户、群组
会话session_id对话(书面材料里不写「对话」)

同一屏出现两种叫法即为缺陷。

3. 视图状态必须枚举完

每个数据视图给出四种形态的文案模板:加载中、正常、错误、空状态(empty state)。

CampusClaw 特有的第五种形态——检索无命中:阈值 SEARCH_VECTOR_MIN 未越过时不显示空白列表,显示「资料中未找到相关内容」,并给出两个下一步动作:换关键词、联系本班教师补充资料。

4. 表单与校验时机

  • 上传表单:选择文件即时校验类型与大小,提交时再校验总数上限;通过后才有进度条。
  • 提问输入框:失焦不校验,提交时校验非空与长度上限;发送后输入框禁用至流式返回结束。
  • 教师入口:/console 只在 /api/me 返回 teacher 时渲染。隐藏入口不是授权手段,服务端仍会拒绝。

5. 视觉基线按令牌写

只定义令牌与层级,不写每页像素值:间距刻度(4 / 8 / 16 / 24 / 32)、字号层级(正文 / 小标题 / 页面标题三级)、语义色三项(成功 / 警告 / 错误)。组件清单固定为:按钮、输入、文件上传、列表、代码块、引用块、出处卡片。

新增页面必须复用清单中的组件;出现自造样式即判违规。

6. 可达性与响应式下限

键盘可走完「登录 → 资料详情 → 提问」;所有表单控件有关联标签;正文对比度达标;断点两档(窄屏单列、宽屏双列)。

违反时

先确认写入口意义:若页面清单与术语表因此失同步,两处都改,并记入变更说明。