jiapu/design.md

Design · 代代相传家谱 PC

这是 PC 家谱项目的统一设计系统。所有页面沿用同一套品牌、排版、间距、状态和交互规则；新增规则先修改本文件，不在单个页面创建另一套视觉语言。

用户与任务

• 用户：家谱创建者、管理员、普通家人和浏览公开家谱的访客。
• 核心任务：创建或加入家谱，维护世系与成员，发布并浏览家族内容，处理邀请、消息与服务。
• 设计气质：中文编辑式、克制、可信。功能页以任务效率为先，公共页保留家族文化氛围。

Genre

Editorial。登录后的应用页使用更紧凑的工作台表达，不采用营销页式的大标题和卡片堆叠。

Macrostructure family

• 公开与营销页面：Content Portal。真实内容和图片优先，标题区只说明当前任务。
• 登录后应用页面：Workbench。固定页头、稳定的分组侧栏和单一内容画布；跨页面导航位置不改变。
• 内容与资料页面：Long Document / List Detail。列表进入独立详情页，桌面端需要连续比较时允许页内列表详情。

Theme

• --color-paper: oklch(97.5% 0.012 82)
• --color-paper-2: oklch(94.8% 0.024 78)
• --color-ink: oklch(31% 0.028 158)
• --color-ink-2: oklch(51% 0.022 158)
• --color-rule: oklch(86% 0.028 78)
• --color-accent: oklch(56% 0.185 29)
• --color-accent-strong: oklch(43% 0.13 29)
• --color-focus: oklch(61% 0.17 29)
• 辅助绿色和金色仅用于状态与文化信息，不与主操作竞争。

Typography

• Display：STSong, Songti SC, SimSun, serif；字重 600；正常体。
• Body：Microsoft YaHei, PingFang SC, system-ui, sans-serif；字重 400/600。
• Mono：Consolas, SFMono-Regular, monospace，仅用于编号和技术值。
• 标题不得使用斜体，不保留无业务意义的英文眉题。
• 正文舒适行宽为 62～76 个中文字符。

Spacing

使用根目录 tokens.css 中的 4px 命名刻度。新样式只能使用 --space-*，页面内容区桌面最大宽度统一为 --layout-max。

Motion

• 动效只表达悬停、焦点、展开和状态变化，最多使用透明度与 transform。
• 默认 160～220ms，无弹跳和持续漂浮。
• prefers-reduced-motion 下关闭空间位移并将反馈压缩为短暂透明度变化。

Interaction decisions

• 独立页面：多字段创建/编辑、详情阅读、支付、权限和安全设置。
• 对话框：删除/退出等不可逆确认、密码输入、单一短任务；统一使用站内对话框，不调用浏览器原生 confirm/prompt。
• 图片灯箱：相册和内容图片预览；不改变当前列表位置。
• 页内展开：帮助问答、筛选、非关键补充信息。
• 抽屉：桌面端评论或需要保留主内容上下文的辅助任务；不承载长表单。
• 加载、空数据、错误、无权限：显示在对应内容区域，不使用弹窗打断。
• 成功反馈：优先更新页面状态；仅在用户可能看不到变化时使用短消息。

Media rules

• 业务媒体只消费后端 BusinessFileAccess.accessUrl，不得拼接 OSS ID 或暴露内部路径。
• 家谱封面 16:9；相册封面 4:3；文章封面 16:9；头像 1:1；动态媒体根据原图比例限制最大高度。
• 有地址时显示真实图片；无图片时使用姓名首字或明确空状态，不使用伪造照片、CSS 图画或无意义占位块。
• 图片必须有与业务内容对应的替代文本；装饰图片使用空替代文本。
• 正文附件使用左对齐、最大 280px 的缩略图网格并完整显示原图；封面和视频预览按业务比例完整呈现，不把单张附件拉伸成整栏大图。
• 视频使用原生播放器，列表中只自动加载封面，不自动播放。

Shared states

所有交互控件必须覆盖默认、悬停、键盘焦点、按下、禁用、加载、错误、成功状态。错误信息靠近问题区域，同时保留可恢复操作。

Responsive

• 验证宽度：320、375、414、768、1024、1440。
• 768px 以下侧栏转为页内分组导航，主内容单列。
• html 与 body 使用 overflow-x: clip；按钮和主导航文字不得折成两行。
• 附件网格桌面端按 200–280px 自适应列展示，移动端保持最大 280px；标题允许长家谱名称安全换行。

What pages MUST share

• 品牌标识、朱红主操作色、排版和按钮语气。
• 页头高度、内容最大宽度、侧栏位置、表单控件高度和状态样式。
• 图片比例、媒体错误回退、空状态和权限状态。

Per-page allowances

• 公开页可使用仓库内已有的真实祠堂和服务图片。
• 应用页不增加装饰插画，数据与操作本身承担视觉层级。
• 内容页以标题、正文、真实封面和元信息为主。

Exports

实际 CSS 变量以根目录 tokens.css 为准。项目为原生 HTML/CSS/JS，不启用 Tailwind 或 shadcn；如未来迁移，颜色、字体、间距必须从相同命名 token 映射，不得另建品牌值。