ray-template/docs/ui-design.md
XiaoDaiGua-Ray 39d2e82439 feat: enhance template layouts, hooks, and icon workflow
Add interactive hook examples, shared Pinia runtime state, and configurable layouts.
Generate typed namespaced icons during development, HMR, and builds.
Refine the UI and establish project comment and design conventions.

Validation: typecheck, ESLint, 181 tests, and production build passed.
2026-11-03 13:17:58 +08:00

2.2 KiB
Raw Blame History

页面视觉与排版

模板采用克制的蓝色与中性色。精致感来自一致的层级、间距与密度,而非给每个区域增加阴影或装饰。

主题与尺度

  • 页面背景、卡片、分割线与文字优先使用 src/styles/design-system.scss 中的语义变量。Naive UI 的主题覆盖集中在 src/app-config/design-config.ts,保持同一色阶,避免页面单独拼出另一套主题。
  • 控件通常为 8px 圆角、卡片为 12px;页面区块间距使用 20–28px。强调色用于选择与主要操作,正文、说明、眉题使用不同文字层级。
  • 顶栏、标签栏和侧栏使用轻分割线,不叠加区域阴影;少量内容卡片使用两层轻阴影。
  • 页面标题复用 AppPageHeader:眉题、一个主标题、简短说明与可选操作区。不要以大段说明或同等权重的卡片标题代替页面层级。

页面组织

  • 工作台与说明型示例限制到 1360px 并居中;业务表格仍遵循用户的流式/定宽布局设置,不全局强行收窄。
  • 示例使用 DemoPage 和 HookExample,按功能分组;将交互区域和可展开的代码区域分开。代码展开使用原生 details,支持键盘操作,并保留复制入口。
  • Hooks 在内容容器达到 900px 后显示双列;布局实验室在 760px 后使用设置/预览双栏。容器不足时按默认单列堆叠,判断可用内容宽度,不只看整个浏览器窗口。
  • 先复用现有 Naive UI 与模板组件,再补少量排版结构。不为展示效果编造统计数据;工作台版本号读取实际 package 配置,快捷入口跟随可见菜单。
  • 共用组件的不同调用场景分别保留:例如资源链接在登录页保持 compact,在工作台使用 cards,不以统一排版破坏原有页面约束。

验证

检查桌面与 390px 窄屏、明暗主题、中英文、长代码和操作按钮换行。默认正文用色按至少 4.5:1、输入框等控件边界按至少 3:1 选取;用户自定义主色仍需按实际组合确认。

保留 forced-colors 系统颜色回退、可见键盘焦点与减少动态效果设置。截图、颜色数值与浏览器检查不能互相替代,也不代表已验证全部最低版本设备。