样例:产品设计规范
下面是 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. 可达性与响应式下限
键盘可走完「登录 → 资料详情 → 提问」;所有表单控件有关联标签;正文对比度达标;断点两档(窄屏单列、宽屏双列)。
违反时
先确认写入口意义:若页面清单与术语表因此失同步,两处都改,并记入变更说明。